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, certificated, 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").