.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "provider\-pkcs11" "7" "" "" "Configuration directives"
.SH NAME
pkcs11\-provider \- An OpenSSL provider that allows to directly
interface with pkcs11 drivers.
.SH DESCRIPTION
Starting with version 3.0 the OpenSSL project introduced a new modular
system to extend OpenSSL that replaces the deprecated Engines modules.
.PP
Providers(1) are loaded via configuration directives in the openssl
configuration file (or directly loaded by applications).
.PP
The pkcs11 provider allows applications linked to openssl to use keys
and cryptographic operations from a hardware or software token via their
PKCS#11(2) driver and the use of pkcs11 URIs(3).
.PP
The pkcs11 provider can be configured to be automatically loaded via
openssl.cnf
.SH CONFIGURATION
Configuration options recognized by the provider
.SS pkcs11\-module\-path
A file path to the pkcs11 driver to be used
.PP
Default: If compiled with p11\-kit defaults to its proxy driver,
otherwise none.
.PP
NOTE: See also PKCS11_PROVIDER_MODULE in the environment variables
section.
.PP
Example:
.PP
\f[CR]pkcs11\-module\-path = /usr/lib64/opensc\-pkcs11.so\f[R]
.SS pkcs11\-module\-init\-args
Non\-standard initialization arguments some pkcs11 driver may need.
Generally not used, but some software tokens like NSS\[cq]s softokn
require this.
.PP
Default: None
.PP
Example:
.PP
\f[CR]pkcs11\-module\-init\-args = configDir=/etc/pki/token\f[R]
.SS 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 terminator.
.PP
Default: None
.PP
Example:
.PP
\f[CR]pkcs11\-module\-token\-pin = file:/etc/pki/pin.txt\f[R]
.IP
.EX
cat /etc/pki/pin.txt
123456
.EE
.SS 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\[cq]s code.
.PP
Default: 0 (Allow Export)
.PP
Example:
.PP
\f[CR]pkcs11\-module\-allow\-export = 1\f[R] (This disallows export of
public keys)
.SS 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.
.PP
Two options are available: * true * false
.PP
Default: true (Note: if the token does not support session caching, then
caching will be auto\-disabled after the first attempt)
.PP
Example:
.PP
\f[CR]pkcs11\-module\-cache\-keys = false\f[R] (Disable any attempt of
caching keys in the session)
.SS 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.
.PP
Only one option is currently available: * cache: Caches the PIN
.PP
Default: unset (No caching)
.PP
Example:
.PP
\f[CR]pkcs11\-module\-cache\-pins = cache\f[R] (Will cache a pin that
has been entered manually)
.SS 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.
.PP
Default: 5
.PP
Example:
.PP
\f[CR]pkcs11\-module\-cache\-sessions = 0\f[R] (Disables caching)
.SS pkcs11\-module\-login\-behavior
Whether the pkcs11 provider will attempt to login to the token when a
public key is being requested.
.PP
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
.PP
Default: \[lq]auto\[rq]
.PP
Example:
.PP
\f[CR]pkcs11\-module\-login\-behavior = always\f[R] (Always tries to
login before loading public keys)
.SS 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).
.PP
Only one option is available: * early: Loads the pkcs11 module
immediately
.PP
Default: unset (Loads only at first use)
.PP
Example:
.PP
\f[CR]pkcs11\-module\-load\-behavior = early\f[R] (Loads pkcs11 module
immediately at application startup)
.SS pkcs11\-module\-quirks
Workarounds that may be needed to deal with some tokens and cannot be
autodetcted yet are not appropriate defaults.
.SS no\-deinit
It prevents de\-initing when OpenSSL winds down the provider.
NOTE this option may leak memory and may cause some modules to misbehave
if the application intentionally unloads and reloads them.
.SS no\-operation\-state
OpenSSL by default assumes contexts with operations in flight can be
easily duplicated.
That is only possible if the tokens support getting and setting the
operation state.
If the quirk is enabled the context duplication is not performed.
.SS no\-session\-callbacks
Some implementatations of PKCS11 don\[cq]t allow setting
\f[CR]pApplication\f[R] and \f[CR]Notify\f[R] callback functions in
\f[CR]C_OpenSession\f[R].
This option sets NULL values for both callbacks.
.SS no\-allowed\-mechanisms
Some implementatations of PKCS11 don\[cq]t support
\f[CR]CKA_ALLOWED_MECHANISMS\f[R] attribute on keys.
Setting this quirk prevents the provider from attempting to set and read
this attribute.
.PP
Default: none
.PP
Example:
.PP
\f[CR]pkcs11\-module\-quirks = no\-deinit no\-operation\-state\f[R]
(Disables deinitialization, blocks context duplication)
.SS pkcs11\-module\-block\-operations
Allows to block specific \[lq]provider operations\[rq] even if the token
actually supports the necessary mechanisms.
This is useful to work around cases where one wants to enforce use of
the token for all operations by setting ?provider=pkcs11 in the default
properties but wants an exception for a specific type of operation like
digests.
NOTE: some operations may depend on others or may be fundamental to the
correct working of the provider, so not all configurations of this
parameter will work.
Use carefully.
.PP
Default: none
.PP
Example: \f[CR]pkcs11\-module\-block\-operations = digest\f[R] (Disables
digest mechanisms, which will be instead routed to the OpenSSL default
provider in most configurtions)
.SS pkcs11\-module\-assume\-fips
Assume the token used by the PKCS#11 module is FIPS certified.
.PP
Due to the incomplete specification for signalization of the
certification from the pkcs11 modules, this can not be determined
automatically.
If you know your token is FIPS certified, you need to set this
configuration option to true.
Otherwise the pkcs11\-provider will not work in FIPS Mode.
.PP
Default: False
.PP
Example:
.PP
\f[CR]pkcs11\-module\-assume\-fips = true\f[R]
.SH ENVIRONMENT VARIABLES
Environment variables recognized by the provider
.SS 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 \f[B]overrides\f[R] the pkcs11\-module\-path
option sets in openssl.cnf
.PP
Example:
.PP
\f[CR]PKCS11_PROVIDER_MODULE = /usr/lib64/opensc\-pkcs11.so\f[R]
.SS PKCS11_PROVIDER_DEBUG
This variable can be set to obtain debug information.
Two sub\-options can be specified: file, level
.PP
The normal debug_level is 1, if a higher level is provider then
additional information (like all supported mechanism info for each slot)
is printed in the specified debug file.
The comma character separates options, and the colon character is used
to separate an option and its value.
There is no escape character, therefore the characters `,' and `:'
cannot be used in values.
.PP
Examples:
.PP
\f[CR]PKCS11_PROVIDER_DEBUG=file:/tmp/debug.log\f[R]
.PP
\f[CR]PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2\f[R]
.SH USE IN OLDER APPLICATIONS (URIs in PEM files)
It is strongly suggested to update applications to use the new
OSSL_STORE API provided by OpenSSL 3.0 which accepts URIs to
transparenly load keys from either files or any other supported
mechanism including PKCS#11 URIs.
.PP
However, for those applications that cannot yet be changed, there is
tool to generate a \[lq]wrapper\[rq] PEM file that contains the PKCS#11
URI needed to identify a key on the a token.
.PP
This PEM file can be loaded via the clasic methods used to parse PEM/DER
representations of keys and will trigger the use of the pkcs11\-provider
decoders when the provider is loaded.
An error will be returned if the provider is not pre\-loaded or an older
version of OpenSSL is used.
.PP
In tools/uri2pem.py there is a sample python script that can take a key
URI and produce a PEM file that references it.
Note that storing PINs within these PEM files is not secure.
These files are not encrypted.
.PP
The follwing command can be used to list all keys on a token and print
their identifying URI:
.IP
.EX
openssl storeutl \-keys \-text pkcs11:
.EE
.SH EXAMPLES
openssl.cnf:
.IP
.EX
HOME = .

# Use this in order to automatically load providers.
openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect

[default_sect]
activate = 1

[pkcs11_sect]
module = /usr/lib64/ossl\-modules/pkcs11.so
pkcs11\-module\-path = /usr/lib64/pkcs11/vendor_pkcs11.so
pkcs11\-module\-token\-pin = /etc/ssl/pinfile.txt
activate = 1
.EE
.SH SEE ALSO
.IP "1." 3
PROVIDER(7) man page \-
https://www.openssl.org/docs/manmaster/man7/provider.html
.IP "2." 3
PKCS#11 Technical committe and standards \-
https://www.oasis\-open.org/committees/tc_home.php?wg_abbrev=pkcs11
.IP "3." 3
PKCS#11 URI Scheme \- RFC 7512 \-
https://www.rfc\-editor.org/rfc/rfc7512
