OpenSSL 3.0: PKCS#11 provider for signing operations

Edit online

Learn how to configure a PKCS#11 provider for signing operations in a way that it protects the private keys for TLS sessions in a hardware security module (HSM).

You can use the PKCS#11 provider called pkcs11-sign-provider to support signing operations on existing asymmetric keys with an openCryptoki library. These keys must be referenced by a PKCS#11 URI. The main purpose of the pkcs11-sign-provider is to protect the private keys for TLS sessions by a hardware security module (HSM).

You can use the pkcs11-sign-provider from a containing distribution or download the source and build it yourself: pkcs11-sign-provider from GitHub

Description

The pkcs11-sign-provider provides cryptographic operations on asymmetric key material which is available in PKCS#11 infrastructure, (for example, openCryptoki), and which is referenced by a PKCS#11 URI. The pkcs11-sign-provider registers a key storage for PKCS#11 URIs. The provider only processes algorithms with existing (private) asymmetric keys in the related PKCS#11 token. All other actions are handled by the forward-provider as clear-key operations.

In your applications, you can use the following supported PKCS#11 mechanisms:

  • for RSA:
    • CKM_RSA_PKCS
    • CKM_RSA_PKCS_OAEP
    • CKM_RSA_PSS
    • CKM_RSA_X_509
  • for ECC:
    • CKM_ECDSA

The pkcs11-sign-provider does not support key creation or removal of PKCS#11 keys. For key management, external tools are required. The provider supports the PKCS#11 URI scheme as specified in RFC 7512. Only a subset of the specified query attributes are supported in such URIs. The query module attributes module-name and module-path are tolerated but ignored by the pkcs11-sign-provider.

For PINs, which are required to access key objects in PKCS#11 tokens, the pkcs11-sign-provider supports PINs in the PKCS#11 URI by value (pin-value) or by reference to a file (pin-source).

PKCS#11 signing provider configuration

The OpenSSL configuration of the application must refer to a provider section for the pkcs11-sign-provider. This can be in the system-wide OpenSSL configuration file (for example, /etc/ssl/openssl.conf) or in an application-specific OpenSSL configuration file (referenced by the environment variable OPENSSL_CONF).

Mandatory parameters in the provider section for the pkcs11-sign-provider are:

  • path to the pkcs11-sign-provider module (shared object)
  • shared object name of the PKCS#11 library, for example, libopencryptoki.so or libpkcs11.so, or path to it for use with openCryptoki.

Optionally, the provider section for the pkcs11-sign-provider can specify initialization arguments for the PKCS#11 library. Another optional parameter can specify the name (identity) of a forward-provider. If no forward-provider is specified, the built-in default provider of OpenSSL is used.

To use the pkcs11-sign-provider, specify it in the application's property query. You achieve this either by specifying the default property query in the algorithm section of the OpenSSL configuration file, or by setting it in the provider context.

The key references must follow the PKCS#11 URI as specified in RFC 7512: The PKCS #11 URI Scheme. A key URI must also contain the PIN for the PKCS#11 token by value or by reference to a file (recommended).

For more information about the configuration file, see the man-page of the pkcs11sign.cnf - Configuration for OpenSSL PKCS#11 sign provider module . For more information about the application interface, see section APPLICATION INTERFACE in the man-page of the pkcs11sign - OpenSSL PKCS#11 sign provider module.