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