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