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-module-init-args (optional)

The pkcs11sign-module-init-args takes a parameter string, which is used during the initialization of the Cryptoki module.

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.

EVP Configuration (alg_section)¶

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

Configuration example¶

This configuration example shows

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