Skip to content

Home

Jump to bottom
Simo Sorce edited this page May 3, 2023 · 7 revisions

Provider configuration variables in openssl.cnf section

pkcs11-module-path

A file path to the pkcs11 driver to be used

Default: None (but see the environment variables section)

Example:

pkcs11-module-path = /usr/lib64/opensc-pkcs11.so

pkcs11-module-init-args

Non-standard initialization arguments some pkcs11 driver may need. Generally not used, but some software tokens like NSS's softokn require this.

Default: None

Example:

pkcs11-module-init-args = configDir=/etc/pki/token

pkcs11-module-token-pin

The user PIN to be used with the token. If a PIN is not set in configuration it can be asked interactively (if the application uses prompters), or it can be specified together with the key identifiers in the pkcs11 URI directly. When a file is specified the file must be a text file containing just the PIN on the first line and a \n terminator.

Default: None

Example:

pkcs11-module-token-pin = file:/etc/pki/pin.txt

cat /etc/pki/pin.txt
123456

pkcs11-module-allow-export

Whether the pkcs11 provider will allow to export public keys through OpenSSL. OpenSSL often tries to export public keys from non-default providers to the default provider, and then use OpenSSL own functions to handle whatever operation is associated with the public key. This option can be useful to force public key operations to be executed on the token, for example in case the pkcs11 is an accelerator that has better performance on signature checking or asymmetric encryption than OpenSSL's code.

Default: 0 (Allow Export)

Example:

pkcs11-module-allow-export = 1 (This disallows export of public keys) pkcs11-module-cache-pins = cache (Will cache a pin that has been entered manually)

pkcs11-module-cache-keys

Whether the pkcs11-provider should ask the token to cache token keys in the session. This is used in some tokens as a performance optimizations. For example software tokens that store keys encrypted can keep a copy of the key in the session to speed up access. Or Networked HSMs that allow exporting key material can cache the key in the session instead of re-requesting it over the network.

Two options are available:

  • true
  • false

Default: true (Note: if the token does not support session caching, then caching will be auto-disabled after the first attempt)

Example:

pkcs11-module-cache-keys = false (Disable any attempt of caching keys in the session)

pkcs11-module-cache-pins

Whether the pkcs11-provider should cache a pin entered interactively. This is useful to allow starting a service and providing the pin only manually, yet let the service perform multiple logins as needed, for example after forking.

Only one option is currently available:

  • cache: Caches the PIN

Default: unset (No caching)

Example:

pkcs11-module-cache-sessions

Allows to tune how many pkcs11 sessions may be kept open and cached for rapid use. This parameter is adjusted based on the maximum number of sessions the token declares as supported. Note that the login session is always cached to keep the token operable.

Default: 5

Example:

pkcs11-module-cache-sessions = 0 (Disables caching)

pkcs11-module-login-behavior

Whether the pkcs11 provider will attempt to login to the token when a public key is being requested.

Three options are available:

  • auto: Try without but fallback to login behavior if no keys are found
  • always: Always login before trying to load public keys (this is required by some HSMs)
  • never: Never login for public keys

Default: "auto"

Example:

pkcs11-module-login-behavior = always (Always tries to login before loading public keys)

pkcs11-module-load-behavior

Whether the pkcs11-provider immediately loads an initializes the pkcs11 module as soon as OpenSSL loads the provider (generally at application startup), or defer initialization until the first time a pkcs11 key is loaded (or some other operation explicitly requiring the pkcs11 provider is requested).

Only one option is available:

  • early: Loads the pkcs11 module immediately

Default: unset (Loads only at first use)

Example:

pkcs11-module-load-behavior = early (Loads pkcs11 module immediately at application startup)

pkcs11-module-quirks

Workarounds that may be needed to deal with some tokens and cannot be autodetcted yet are not appropriate defaults.

The only quirk currently implemented is "no-deinit" It prevent de-initing when OpenSSL winds down the provider. NOTE this option may leak memory and may cause some modules to misbehaves if the application intentionally unloads and reloads them.

Default: none

Example:

pkcs11-module-quirks = no-deinit (Disables deinitialization)

Environment variables recognized by the pkcs11-provider

PKCS11_PROVIDER_MODULE

This variable can be used to set a different pkcs11 driver to be used. It is useful when an application needs to use a different driver than the rest of the system. This environment variable overrides the pkcs11-module-path option sets in openssl.cnf

Example:

PKCS11_PROVIDER_MODULE = /usr/lib64/opensc-pkcs11.so

PKCS11_PROVIDER_DEBUG

This variable can be set to obtain debug information. Two sub-options can be specified: file, level The normal debug_level is 1, if a higher level is provider then additional information (like all supported mechanism info for exach slot) is printed in the specified debug file. The comma character separates options, and the colon character is used to separate an option and it's value. There is no escape character, therefore the characters , and : cannot be used in values.

Examples:

PKCS11_PROVIDER_DEBUG=file:/tmp/debug.log

PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2

Clone this wiki locally