pkcs11sign - Man Page

OpenSSL PKCS#11 sign provider module

Description

The pkcs11-sign-provider implements the OpenSSL 3.0 provider interface and provides cryptographic operation on asymmetric key material, available in PKCS#11 infrastructure (e.g. opencryptoki). The pkcs11-sign-provider will register a key storage for PKCS#11 URIs (RFC 7512). All keys which are referenced by a PKCS#11 URI will be handled by the pkcs11-sign-provider. Other keys (e.g.  file-based) are forwarded by the pkcs11-sign-provider to another OpenSSL-Provider, e.g. the built-in OpenSSL default provider.

The pkcs11-sign-provider will only process algorithms with existing (private) asymmetric keys in the related PKCS11-token. All other actions will be handled by the forward-provider as clear-key operations.

The pkcs11-sign-provider does not support key creation or removal of PKCS#11 keys. For key management, external tools are required.

Supported PKCS#11 mechanisms for RSA:

Supported PKCS#11 mechanisms for EC:

Application Interface

An application, which should use asymmetric keys in PKCS#11 infrastructure, must use an OpenSSL configuration for the pkcs11-sign-provider and refer to the keys by an PKCS#11 URI. The rest of the application should not need any changes.

Configuration

If the system-wide OpenSSL configuration does not configure the pkcs11-sign-provider, the application can use its own OpenSSL configuration file and refer to it in its environment variable OPENSSL_CONF. For more details about the configuration see pkcs11sign.cnf(5).

Key references

Instead of referring to a private key file (e.g. "file:/path/to/key.pem"), the application should use the PKCS#11 URI of the key ("pkcs11:<path-attributes>?<queue-attributes>").

The PKCS#11 URI should specify path parameters of the key, at least the ID or label of the key, as well as its type. The key reference should be unique.

Example for a PKCS#11 URI to a private key:

pkcs11:token=mytok;object=ec-key;type=private&pin-source=/path/to/token-pinfile.txt
Note

The current version of pkcs11-sign-provider supports only the queue parameters pin-value and pin-source. All other queue parameters are not yet supported.

PIN handling

The PIN is required to login to a PKCS#11 token, to manage or work with sensitive PKCS#11 objects (keys) and should not be proposed to anyone without a need-to-know.

An application, which is using key material in a PKCS#11 token, has such a need-to-know, so the PIN should be under control of the application.

The pkcs11-sign-provider supports the PIN handling in the PKCS#11 URI with the queue attributes pin-value and pin-source. While the first one contains the plain-text PIN, the latter one refers to a file, which contains the PIN. It is highly recommended to use the file reference and set the access permissions of the PIN file accordingly.

PIN file

The PIN gives access to a PKCS#11 token and its objects (keys, certificates, data). It should be treated as a secret information and only the application should have access to it. With the right setup, the usage of a PIN file provides the best protection for the PIN.

Rules for the PIN file:

  • one PIN per PIN file
  • the PIN file must only contain the PIN, no comments, no linefeed or other characters
  • the PIN file must be readable by the application
  • the PIN file should not be writable by the application
  • the PIN file must not be readable nor writable by other unprivileged users.

The following snippet shows, how to create a protected PIN file. It will prompt for the PIN and write it to a file, which is only accessible for the user.

PINFILE="/path/to/my_pinfile.txt"
touch "${PINFILE}"
chmod u=rw,g=,o= "${PINFILE}"
(read -rsp "Enter PIN: " PIN; echo -n ${PIN}) > "${PINFILE}"

If required, the file ownership can later be changed to another user and group. This would require extra capabilities (e.g. by using "sudo").

See Also

pkcs11sign.cnf(5), EVP(7)

Referenced By

pkcs11sign.cnf(5).

2022-11-21