OpenSSL Configuration

The pkcs11-sign-provider can be configured application-specific or system-wide. In both cases, the configuration file need to define and reference a section for the pkcs11-sign-provider, following the OpenSSL configuration syntax (config(5)).

The pkcs11-sign-provider section specifies the shared library of the provider itself (mandatory), the shared library of the Cryptoki implementation (mandatory) and initialization parameters for the Cryptoki implementation (optional). It is also possible to specify a forward provider. If no forward provider is specified, the OpenSSL built-in default-provider is selected.

The pkcs11-sign-provider must also be preferred in the algorithm-properties, so that all requests are directed to the pkcs11-sign-provider. This can either be done in the application or in the configuration file (recommended).

Provider Section

A provider section in the OpenSSL configuration define generic parameters, as well as provider-specific parameters. Each provider section can be references in a providers sections. The pkcs11-sign-provider requires at least the generic provider section parameters module, identity, and activate. For more details about the generic provider parameters, see config(5).

module (mandatory)

This parameter takes a path to the provider shared object file. For the pkcs11-sign-provider, use the path to the installation location of pkcs11sign.so (provider shared object).

identity (optional)

This parameter specifies an alias name for the provider and overrides the provider name in the providers section. It is recommended to use the same name as in the providers.

activate (optional)

If present, this parameter activates the provider section.

The pkcs11-sign-provider defines the provider specific parameters pkcs11sign-module-path, pkcs11sign-module-init-args, and pkcs11sign-forward.

pkcs11sign-module-path (mandatory)

This parameter takes the path to the shared object file of a PKCS#11 Cryptoki module implementation. The provider can be used with PKCS#11 Cryptoki modules, implementing the PKCS#11 standard version 3.0 (or compatible).

pkcs11sign-forward (optional)

The pkcs11sign-forward parameter takes the name of a provider, to which all operations are forwarded, which are not handled by the pkcs11-sign-provider itself, e.g. key derivation for ECDHE. If this parameter is not specified in the provider section, the pkcs11-sign-provider will use the built-in OpenSSL default provider as forward.

The syntax for this parameter is "provider=<name_of_forward_provider>". See the configuration example for more details.

pkcs11sign-module-init-args (optional, not PKCS#11-3.0 conform)

The pkcs11sign-module-init-args takes a parameter string whose reference is passed to the Cryptoki module as pReserved in CK_C_INITIALIZE_ARGS during initialization.

Note: The PKCS#11 standard v3.0 specifies that the initialization of a Cryptoki module fails if pReserved is not a NULL_PTR. This parameter will only work with Cryptoki modules (e.g. libnss) which do not implement this strict behavior. A Cryptoki module, which strictly implements the PKCS#11 standard v3.0 will fail on C_Initialize() with CKR_ARGUMENTS_BAD if this parameter is set.

EVP Configuration (alg_section)

This section configures the algorithm-properties for the EVP API. The pkcs11-sign-provider should be set as the preferred provider for all EVP algorithms by adding the expression "?provider=pkcs11sign" to the default_properties.

Configuration example

This example shows a pkcs11-sign-provider configuration for opencryptoki.

openssl_conf = openssl_init
[openssl_init]
providers = provider_sect
alg_section = evp_properties
[provider_sect]
default = default_sect
base = base_sect
pkcs11sign = pkcs11sign_sect
[evp_properties]
default_properties = ?provider=pkcs11sign
[pkcs11sign_sect]
module = /path/to/pkcs11sign.so
identity = pkcs11sign
pkcs11sign-module-path = /path/to/libopencryptoki.so.0
pkcs11sign-forward = provider=default
activate = 1