PKCS11SIGN(7)

NAME
pkcs11sign - 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:

•   CKM_RSA_PKCS

•   CKM_RSA_PKCS_OAEP

•   CKM_RSA_PSS

•   CKM_RSA_X_509

Supported PKCS#11 mechanisms for EC:

•   CKM_ECDSA

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)

Copyright
Copyright © International Business Machines Corp. 2022, 2023