1provider-pkcs11(7) Configuration directives provider-pkcs11(7)
2
6 pkcs11-provider - An OpenSSL provider that allows to directly interface
7 with pkcs11 drivers.
8
10 Starting with version 3.0 the OpenSSL project introduced a new modular
11 system to extend OpenSSL that replaces the deprecated Engines modules.
12 Providers(1) are loaded via configuration directives in the openssl
14 configuration file (or directly loaded by applications).
15 The pkcs11 provider allows applications linked to openssl to use keys
17 and cryptographic operations from a hardware or software token via
18 their PKCS#11(2) driver and the use of pkcs11 URIs(3).
19 The pkcs11 provider can be configured to be automatically loaded via
21 openssl.cnf
22
24 Configuration options recognized by the provider
25 pkcs11-module-path
27 A file path to the pkcs11 driver to be used
28 Default: If compiled with p11-kit defaults to its proxy driver, other‐
30 wise none.
31 NOTE: See also PKCS11_PROVIDER_MODULE in the environment variables sec‐
33 tion.
34 Example:
36 pkcs11-module-path = /usr/lib64/opensc-pkcs11.so
38 pkcs11-module-init-args
40 Non-standard initialization arguments some pkcs11 driver may need.
41 Generally not used, but some software tokens like NSS’s softokn require
42 this.
43 Default: None
45 Example:
47 pkcs11-module-init-args = configDir=/etc/pki/token
49 pkcs11-module-token-pin
51 The user PIN to be used with the token. If a PIN is not set in config‐
52 uration it can be asked interactively (if the application uses
53 prompters), or it can be specified together with the key identifiers in
54 the pkcs11 URI directly. When a file is specified the file must be a
55 text file containing just the PIN on the first line and a terminator.
56 Default: None
58 Example:
60 pkcs11-module-token-pin = file:/etc/pki/pin.txt
62 cat /etc/pki/pin.txt
64 123456
65 pkcs11-module-allow-export
67 Whether the pkcs11 provider will allow to export public keys through
68 OpenSSL. OpenSSL often tries to export public keys from non-default
69 providers to the default provider, and then use OpenSSL own functions
70 to handle whatever operation is associated with the public key. This
71 option can be useful to force public key operations to be executed on
72 the token, for example in case the pkcs11 is an accelerator that has
73 better performance on signature checking or asymmetric encryption than
74 OpenSSL’s code.
75 Default: 0 (Allow Export)
77 Example:
79 pkcs11-module-allow-export = 1 (This disallows export of public keys)
81 pkcs11-module-cache-keys
83 Whether the pkcs11-provider should ask the token to cache token keys in
84 the session. This is used in some tokens as a performance optimiza‐
85 tions. For example software tokens that store keys encrypted can keep
86 a copy of the key in the session to speed up access. Or Networked HSMs
87 that allow exporting key material can cache the key in the session in‐
88 stead of re-requesting it over the network.
89 Two options are available: * true * false
91 Default: true (Note: if the token does not support session caching,
93 then caching will be auto-disabled after the first attempt)
94 Example:
96 pkcs11-module-cache-keys = false (Disable any attempt of caching keys
98 in the session)
99 pkcs11-module-cache-pins
101 Whether the pkcs11-provider should cache a pin entered interactively.
102 This is useful to allow starting a service and providing the pin only
103 manually, yet let the service perform multiple logins as needed, for
104 example after forking.
105 Only one option is currently available: * cache: Caches the PIN
107 Default: unset (No caching)
109 Example:
111 pkcs11-module-cache-pins = cache (Will cache a pin that has been en‐
113 tered manually)
114 pkcs11-module-cache-sessions
116 Allows to tune how many pkcs11 sessions may be kept open and cached for
117 rapid use. This parameter is adjusted based on the maximum number of
118 sessions the token declares as supported. Note that the login session
119 is always cached to keep the token operable.
120 Default: 5
122 Example:
124 pkcs11-module-cache-sessions = 0 (Disables caching)
126 pkcs11-module-login-behavior
128 Whether the pkcs11 provider will attempt to login to the token when a
129 public key is being requested.
130 Three options are available: * auto: Try without but fallback to login
132 behavior if no keys are found * always: Always login before trying to
133 load public keys (this is required by some HSMs) * never: Never login
134 for public keys
135 Default: “auto”
137 Example:
139 pkcs11-module-login-behavior = always (Always tries to login before
141 loading public keys)
142 pkcs11-module-load-behavior
144 Whether the pkcs11-provider immediately loads an initializes the pkcs11
145 module as soon as OpenSSL loads the provider (generally at application
146 startup), or defer initialization until the first time a pkcs11 key is
147 loaded (or some other operation explicitly requiring the pkcs11
148 provider is requested).
149 Only one option is available: * early: Loads the pkcs11 module immedi‐
151 ately
152 Default: unset (Loads only at first use)
154 Example:
156 pkcs11-module-load-behavior = early (Loads pkcs11 module immediately at
158 application startup)
159 pkcs11-module-quirks
161 Workarounds that may be needed to deal with some tokens and cannot be
162 autodetcted yet are not appropriate defaults.
163 The only quirk currently implemented is “no-deinit” It prevent de-init‐
165 ing when OpenSSL winds down the provider. NOTE this option may leak
166 memory and may cause some modules to misbehave if the application in‐
167 tentionally unloads and reloads them.
168 Default: none
170 Example:
172 pkcs11-module-quirks = no-deinit (Disables deinitialization)
174
176 Environment variables recognized by the provider
177 PKCS11_PROVIDER_MODULE
179 This variable can be used to set a different pkcs11 driver to be used.
180 It is useful when an application needs to use a different driver than
181 the rest of the system. This environment variable overrides the
182 pkcs11-module-path option sets in openssl.cnf
183 Example:
185 PKCS11_PROVIDER_MODULE = /usr/lib64/opensc-pkcs11.so
187 PKCS11_PROVIDER_DEBUG
189 This variable can be set to obtain debug information. Two sub-options
190 can be specified: file, level
191 The normal debug_level is 1, if a higher level is provider then addi‐
193 tional information (like all supported mechanism info for each slot) is
194 printed in the specified debug file. The comma character separates op‐
195 tions, and the colon character is used to separate an option and its
196 value. There is no escape character, therefore the characters `,' and
197 `:' cannot be used in values.
198 Examples:
200 PKCS11_PROVIDER_DEBUG=file:/tmp/debug.log
202 PKCS11_PROVIDER_DEBUG=file:/dev/stderr,level:2
204
206 openssl.cnf:
207 HOME = .
209 # Use this in order to automatically load providers.
211 openssl_conf = openssl_init
212 [openssl_init]
214 providers = provider_sect
215 [provider_sect]
217 default = default_sect
218 pkcs11 = pkcs11_sect
219 [default_sect]
221 activate = 1
222 [pkcs11_sect]
224 module = /usr/lib64/ossl-modules/pkcs11.so
225 pkcs11-module-path = /usr/lib64/pkcs11/vendor_pkcs11.so
226 pkcs11-module-token-pin = /etc/ssl/pinfile.txt
227 activate = 1
228
230 1. PROVIDER(7) man page - https://www.openssl.org/docs/manmas‐
231 ter/man7/provider.html
232 2. PKCS#11 Technical committe and standards - https://www.oasis-
234 open.org/committees/tc_home.php?wg_abbrev=pkcs11
235 3. PKCS#11 URI Scheme - RFC 7512 - https://www.rfc-edi‐
237 tor.org/rfc/rfc7512
238 provider-pkcs11(7)