1p11tool(1) User Commands p11tool(1)
2
6 p11tool - GnuTLS PKCS #11 tool
7
9 p11tool [-flags] [-flag [value]] [--option-name[[=| ]value]] [url]
10 Operands and options may be intermixed. They will be reordered.
12
14 Program that allows operations on PKCS #11 smart cards and security
15 modules.
16 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need
18 to be setup. That is create a .module file in /etc/pkcs11/modules with
19 the contents 'module: /path/to/pkcs11.so'. Alternatively the configu‐
20 ration file /etc/gnutls/pkcs11.conf has to exist and contain a number
21 of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.
22 You can provide the PIN to be used for the PKCS #11 operations with the
24 environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
25
28 Tokens
29 --list-tokens
30 List all available tokens.
31 --list-token-urls
34 List the URLs available tokens.
35 This is a more compact version of --list-tokens.
37 --list-mechanisms
39 List all available mechanisms in a token.
40 --initialize
43 Initializes a PKCS #11 token.
44 --initialize-pin
47 Initializes/Resets a PKCS #11 token user PIN.
48 --initialize-so-pin
51 Initializes/Resets a PKCS #11 token security officer PIN.
52 This initializes the security officer's PIN. When used non-in‐
54 teractively use the GNUTLS_NEW_SO_PIN environment variables to
55 initialize SO's PIN.
56 --set-pin=str
58 Specify the PIN to use on token operations.
59 Alternatively the GNUTLS_PIN environment variable may be used.
61 --set-so-pin=str
63 Specify the Security Officer's PIN to use on token initializa‐
64 tion.
65 Alternatively the GNUTLS_SO_PIN environment variable may be
67 used.
68 Object listing
70 --list-all
71 List all available objects in a token.
72 All objects available in the token will be listed. That includes
74 objects which are potentially unaccessible using this tool.
75 --list-all-certs
77 List all available certificates in a token.
78 That option will also provide more information on the certifi‐
80 cates, for example, expand the attached extensions in a trust
81 token (like p11-kit-trust).
82 --list-certs
84 List all certificates that have an associated private key.
85 That option will only display certificates which have a private
87 key associated with them (share the same ID).
88 --list-all-privkeys
90 List all available private keys in a token.
91 Lists all the private keys in a token that match the specified
93 URL.
94 --list-privkeys
96 This is an alias for the --list-all-privkeys option.
97 --list-keys
99 This is an alias for the --list-all-privkeys option.
100 --list-all-trusted
102 List all available certificates marked as trusted.
103 --export
106 Export the object specified by the URL. This option must not
107 appear in combination with any of the following options: export-
108 stapled, export-chain, export-pubkey.
109 --export-stapled
112 Export the certificate object specified by the URL. This option
113 must not appear in combination with any of the following op‐
114 tions: export, export-chain, export-pubkey.
115 Exports the certificate specified by the URL while including any
117 attached extensions to it. Since attached extensions are a
118 p11-kit extension, this option is only available on p11-kit reg‐
119 istered trust modules.
120 --export-chain
122 Export the certificate specified by the URL and its chain of
123 trust. This option must not appear in combination with any of
124 the following options: export-stapled, export, export-pubkey.
125 Exports the certificate specified by the URL and generates its
127 chain of trust based on the stored certificates in the module.
128 --export-pubkey
130 Export the public key for a private key. This option must not
131 appear in combination with any of the following options: export-
132 stapled, export, export-chain.
133 Exports the public key for the specified private key
135 --info List information on an available object in a token.
137 --trusted
140 This is an alias for the --mark-trusted option.
141 --distrusted
143 This is an alias for the --mark-distrusted option.
144 Key generation
146 --generate-privkey=str
147 Generate private-public key pair of given type.
148 Generates a private-public key pair in the specified token. Ac‐
150 ceptable types are RSA, ECDSA, Ed25519, and DSA. Should be com‐
151 bined with --sec-param or --bits.
152 --generate-rsa
154 Generate an RSA private-public key pair.
155 Generates an RSA private-public key pair on the specified token.
157 Should be combined with --sec-param or --bits.
158 NOTE: THIS OPTION IS DEPRECATED
160 --generate-dsa
162 Generate a DSA private-public key pair.
163 Generates a DSA private-public key pair on the specified token.
165 Should be combined with --sec-param or --bits.
166 NOTE: THIS OPTION IS DEPRECATED
168 --generate-ecc
170 Generate an ECDSA private-public key pair.
171 Generates an ECDSA private-public key pair on the specified to‐
173 ken. Should be combined with --curve, --sec-param or --bits.
174 NOTE: THIS OPTION IS DEPRECATED
176 --bits=num
178 Specify the number of bits for the key generate. This option
179 takes an integer number as its argument.
180 For applications which have no key-size restrictions the
182 --sec-param option is recommended, as the sec-param levels will
183 adapt to the acceptable security levels with the new versions of
184 gnutls.
185 --curve=str
187 Specify the curve used for EC key generation.
188 Supported values are secp192r1, secp224r1, secp256r1, secp384r1
190 and secp521r1.
191 --sec-param=security parameter
193 Specify the security level.
194 This is alternative to the bits option. Available options are
196 [low, legacy, medium, high, ultra].
197 Writing objects
199 --set-id=str
200 Set the CKA_ID (in hex) for the specified by the URL object.
201 This option must not appear in combination with any of the fol‐
202 lowing options: write.
203 Modifies or sets the CKA_ID in the specified by the URL object.
205 The ID should be specified in hexadecimal format without a '0x'
206 prefix.
207 --set-label=str
209 Set the CKA_LABEL for the specified by the URL object. This op‐
210 tion must not appear in combination with any of the following
211 options: write, set-id.
212 Modifies or sets the CKA_LABEL in the specified by the URL ob‐
214 ject
215 --write
217 Writes the loaded objects to a PKCS #11 token.
218 It can be used to write private, public keys, certificates or
220 secret keys to a token. Must be combined with one of
221 --load-privkey, --load-pubkey, --load-certificate option.
222 When writing a certificate object, its CKA_ID is set to the same
224 CKA_ID of the corresponding public key, if it exists on the to‐
225 ken; otherwise it will be derived from the X.509 Subject Key
226 Identifier of the certificate. If this behavior is undesired,
227 write the public key to the token beforehand.
228 --delete
230 Deletes the objects matching the given PKCS #11 URL.
231 --label=str
234 Sets a label for the write operation.
235 --id=str
238 Sets an ID for the write operation.
239 Sets the CKA_ID to be set by the write operation. The ID should
241 be specified in hexadecimal format without a '0x' prefix.
242 --mark-wrap, --no-mark-wrap
244 Marks the generated key to be a wrapping key. The no-mark-wrap
245 form will disable the option.
246 Marks the generated key with the CKA_WRAP flag.
248 --mark-trusted, --no-mark-trusted
250 Marks the object to be written as trusted. This option must not
251 appear in combination with any of the following options: mark-
252 distrusted. The no-mark-trusted form will disable the option.
253 Marks the object to be generated/written with the CKA_TRUST
255 flag.
256 --mark-distrusted
258 When retrieving objects, it requires the objects to be dis‐
259 trusted. This option must not appear in combination with any of
260 the following options: mark-trusted.
261 Ensures that the objects retrieved have the CKA_X_TRUST flag.
263 This is p11-kit trust module extension, thus this flag is only
264 valid with p11-kit registered trust modules.
265 --mark-decrypt, --no-mark-decrypt
267 Marks the object to be written for decryption. The no-mark-de‐
268 crypt form will disable the option.
269 Marks the object to be generated/written with the CKA_DECRYPT
271 flag set to true.
272 --mark-sign, --no-mark-sign
274 Marks the object to be written for signature generation. The
275 no-mark-sign form will disable the option.
276 Marks the object to be generated/written with the CKA_SIGN flag
278 set to true.
279 --mark-ca, --no-mark-ca
281 Marks the object to be written as a CA. The no-mark-ca form
282 will disable the option.
283 Marks the object to be generated/written with the CKA_CERTIFI‐
285 CATE_CATEGORY as CA.
286 --mark-private, --no-mark-private
288 Marks the object to be written as private. The no-mark-private
289 form will disable the option.
290 Marks the object to be generated/written with the CKA_PRIVATE
292 flag. The written object will require a PIN to be used.
293 --ca This is an alias for the --mark-ca option.
295 --private
297 This is an alias for the --mark-private option.
298 --mark-always-authenticate, --no-mark-always-authenticate
300 Marks the object to be written as always authenticate. The
301 no-mark-always-authenticate form will disable the option.
302 Marks the object to be generated/written with the CKA_ALWAYS_AU‐
304 THENTICATE flag. The written object will Mark the object as re‐
305 quiring authentication (pin entry) before every operation.
306 --secret-key=str
308 Provide a hex encoded secret key.
309 This secret key will be written to the module if --write is
311 specified.
312 --load-privkey=file
314 Private key file to use.
315 --load-pubkey=file
318 Public key file to use.
319 --load-certificate=file
322 Certificate file to use.
323 Other options
326 -d num, --debug=num
327 Enable debugging. This option takes an integer number as its
328 argument. The value of num is constrained to being:
329 in the range 0 through 9999
330 Specifies the debug level.
332 --outfile=str
334 Output file.
335 --login, --no-login
338 Force (user) login to token. The no-login form will disable the
339 option.
340 --so-login, --no-so-login
343 Force security officer login to token. The no-so-login form
344 will disable the option.
345 Forces login to the token as security officer (admin).
347 --admin-login
349 This is an alias for the --so-login option.
350 --test-sign
352 Tests the signature operation of the provided object.
353 It can be used to test the correct operation of the signature
355 operation. If both a private and a public key are available
356 this operation will sign and verify the signed data.
357 --sign-params=str
359 Sign with a specific signature algorithm.
360 This option can be combined with --test-sign, to sign with a
362 specific signature algorithm variant. The only option supported
363 is 'RSA-PSS', and should be specified in order to use RSA-PSS
364 signature on RSA keys.
365 --hash=str
367 Hash algorithm to use for signing.
368 This option can be combined with test-sign. Available hash func‐
370 tions are SHA1, RMD160, SHA256, SHA384, SHA512, SHA3-224,
371 SHA3-256, SHA3-384, SHA3-512.
372 --generate-random=num
374 Generate random data. This option takes an integer number as
375 its argument.
376 Asks the token to generate a number of bytes of random bytes.
378 -8, --pkcs8
380 Use PKCS #8 format for private keys.
381 --inder, --no-inder
384 Use DER/RAW format for input. The no-inder form will disable
385 the option.
386 Use DER/RAW format for input certificates and private keys.
388 --inraw
390 This is an alias for the --inder option.
391 --outder, --no-outder
393 Use DER format for output certificates, private keys, and DH pa‐
394 rameters. The no-outder form will disable the option.
395 The output will be in DER or RAW format.
397 --outraw
399 This is an alias for the --outder option.
400 --provider=file
402 Specify the PKCS #11 provider library.
403 This will override the default options in
405 /etc/gnutls/pkcs11.conf
406 --provider-opts=str
408 Specify parameters for the PKCS #11 provider library.
409 This is a PKCS#11 internal option used by few modules.
411 Mainly for testing PKCS#11 modules.
412 NOTE: THIS OPTION IS DEPRECATED
414 --detailed-url, --no-detailed-url
416 Print detailed URLs. The no-detailed-url form will disable the
417 option.
418 --only-urls
421 Print a compact listing using only the URLs.
422 --batch
425 Disable all interaction with the tool.
426 In batch mode there will be no prompts, all parameters need to
428 be specified on command line.
429 -v arg, --version=arg
431 Output version of program and exit. The default mode is `v', a
432 simple version. The `c' mode will print copyright information
433 and `n' will print the full copyright notice.
434 -h, --help
436 Display usage information and exit.
437 -!, --more-help
439 Pass the extended usage information through a pager.
440
444 To view all tokens in your system use:
445 $ p11tool --list-tokens
446 To view all objects in a token use:
448 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
449 To store a private key and a certificate in a token run:
451 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem --label "Mykey"
452 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem --label "Mykey"
453 Note that some tokens require the same label to be used for the cer‐
454 tificate and its corresponding private key.
455 To generate an RSA private key inside the token use:
457 $ p11tool --login --generate-privkey rsa --bits 1024 --label "MyNewKey" --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
458 The bits parameter in the above example is explicitly set because some
459 tokens only support limited choices in the bit length. The output file
460 is the corresponding public key. This key can be used to general a cer‐
461 tificate request with certtool.
462 certtool --generate-request --load-privkey "pkcs11:KEY-URL" --load-pubkey MyNewKey.pub --outfile request.pem
463
465 One of the following exit values will be returned:
466 0 (EXIT_SUCCESS)
468 Successful program execution.
469 1 (EXIT_FAILURE)
471 The operation failed or the command syntax was not valid.
472
474 certtool (1)
475
478 Copyright (C) 2020-2023 Free Software Foundation, and others all rights
479 reserved. This program is released under the terms of the GNU General
480 Public License, version 3 or later
481
483 Please send bug reports to: bugs@gnutls.org
4843.8.2 15 Nov 2023 p11tool(1)