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
15 Program that allows operations on PKCS #11 smart cards and security
16 modules.
17 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need
19 to be setup. That is create a .module file in /etc/pkcs11/modules with
20 the contents 'module: /path/to/pkcs11.so'. Alternatively the configu‐
21 ration file /etc/gnutls/pkcs11.conf has to exist and contain a number
22 of lines of the form 'load=/usr/lib/opensc-pkcs11.so'.
23 You can provide the PIN to be used for the PKCS #11 operations with the
25 environment variables GNUTLS_PIN and GNUTLS_SO_PIN.
26
29 Tokens
30 --list-tokens
31 List all available tokens.
32 --list-token-urls
35 List the URLs available tokens.
36 This is a more compact version of --list-tokens.
38 --list-mechanisms
40 List all available mechanisms in a token.
41 --initialize
44 Initializes a PKCS #11 token.
45 --initialize-pin
48 Initializes/Resets a PKCS #11 token user PIN.
49 --initialize-so-pin
52 Initializes/Resets a PKCS #11 token security officer PIN..
53 This initializes the security officer's PIN. When used non-
55 interactively use the GNUTLS_NEW_SO_PIN environment variables to
56 initialize SO's PIN.
57 --set-pin=string
59 Specify the PIN to use on token operations.
60 Alternatively the GNUTLS_PIN environment variable may be used.
62 --set-so-pin=string
64 Specify the Security Officer's PIN to use on token initializa‐
65 tion.
66 Alternatively the GNUTLS_SO_PIN environment variable may be
68 used.
69 Object listing
71 --list-all
72 List all available objects in a token.
73 All objects available in the token will be listed. That includes
75 objects which are potentially unaccessible using this tool.
76 --list-all-certs
78 List all available certificates in a token.
79 That option will also provide more information on the certifi‐
81 cates, for example, expand the attached extensions in a trust
82 token (like p11-kit-trust).
83 --list-certs
85 List all certificates that have an associated private key.
86 That option will only display certificates which have a private
88 key associated with them (share the same ID).
89 --list-all-privkeys
91 List all available private keys in a token.
92 Lists all the private keys in a token that match the specified
94 URL.
95 --list-privkeys
97 This is an alias for the --list-all-privkeys option.
98 --list-keys
100 This is an alias for the --list-all-privkeys option.
101 --list-all-trusted
103 List all available certificates marked as trusted.
104 --export
107 Export the object specified by the URL. This option must not
108 appear in combination with any of the following options: export-
109 stapled, export-chain, export-pubkey.
110 --export-stapled
113 Export the certificate object specified by the URL. This option
114 must not appear in combination with any of the following
115 options: export, export-chain, export-pubkey.
116 Exports the certificate specified by the URL while including any
118 attached extensions to it. Since attached extensions are a
119 p11-kit extension, this option is only available on p11-kit reg‐
120 istered trust modules.
121 --export-chain
123 Export the certificate specified by the URL and its chain of
124 trust. This option must not appear in combination with any of
125 the following options: export-stapled, export, export-pubkey.
126 Exports the certificate specified by the URL and generates its
128 chain of trust based on the stored certificates in the module.
129 --export-pubkey
131 Export the public key for a private key. This option must not
132 appear in combination with any of the following options: export-
133 stapled, export, export-chain.
134 Exports the public key for the specified private key
136 --info List information on an available object in a token.
138 --trusted
141 This is an alias for the --mark-trusted option.
142 --distrusted
144 This is an alias for the --mark-distrusted option.
145 Key generation
147 --generate-privkey=string
148 Generate private-public key pair of given type.
149 Generates a private-public key pair in the specified token.
151 Acceptable types are RSA, ECDSA, Ed25519, and DSA. Should be
152 combined with --sec-param or --bits.
153 --generate-rsa
155 Generate an RSA private-public key pair.
156 Generates an RSA private-public key pair on the specified token.
158 Should be combined with --sec-param or --bits.
159 NOTE: THIS OPTION IS DEPRECATED
161 --generate-dsa
163 Generate a DSA private-public key pair.
164 Generates a DSA private-public key pair on the specified token.
166 Should be combined with --sec-param or --bits.
167 NOTE: THIS OPTION IS DEPRECATED
169 --generate-ecc
171 Generate an ECDSA private-public key pair.
172 Generates an ECDSA private-public key pair on the specified
174 token. Should be combined with --curve, --sec-param or --bits.
175 NOTE: THIS OPTION IS DEPRECATED
177 --bits=number
179 Specify the number of bits for the key generate. This option
180 takes an integer number as its argument.
181 For applications which have no key-size restrictions the --sec-
183 param option is recommended, as the sec-param levels will adapt
184 to the acceptable security levels with the new versions of
185 gnutls.
186 --curve=string
188 Specify the curve used for EC key generation.
189 Supported values are secp192r1, secp224r1, secp256r1, secp384r1
191 and secp521r1.
192 --sec-param=security parameter
194 Specify the security level.
195 This is alternative to the bits option. Available options are
197 [low, legacy, medium, high, ultra].
198 Writing objects
200 --set-id=string
201 Set the CKA_ID (in hex) for the specified by the URL object.
202 This option must not appear in combination with any of the fol‐
203 lowing options: write.
204 Modifies or sets the CKA_ID in the specified by the URL object.
206 The ID should be specified in hexadecimal format without a '0x'
207 prefix.
208 --set-label=string
210 Set the CKA_LABEL for the specified by the URL object. This
211 option must not appear in combination with any of the following
212 options: write, set-id.
213 Modifies or sets the CKA_LABEL in the specified by the URL
215 object
216 --write
218 Writes the loaded objects to a PKCS #11 token.
219 It can be used to write private, public keys, certificates or
221 secret keys to a token. Must be combined with
222 one of --load-privkey, --load-pubkey, --load-certificate
223 option.
224 --delete
226 Deletes the objects matching the given PKCS #11 URL.
227 --label=string
230 Sets a label for the write operation.
231 --id=string
234 Sets an ID for the write operation.
235 Sets the CKA_ID to be set by the write operation. The ID should
237 be specified in hexadecimal format without a '0x' prefix.
238 --mark-wrap, --no-mark-wrap
240 Marks the generated key to be a wrapping key. The no-mark-wrap
241 form will disable the option.
242 Marks the generated key with the CKA_WRAP flag.
244 --mark-trusted, --no-mark-trusted
246 Marks the object to be written as trusted. The no-mark-trusted
247 form will disable the option. This option must not appear in
248 combination with any of the following options: mark-distrusted.
249 Marks the object to be generated/written with the CKA_TRUST
251 flag.
252 --mark-distrusted
254 When retrieving objects, it requires the objects to be dis‐
255 trusted (blacklisted). This option must not appear in combina‐
256 tion with any of the following options: mark-trusted.
257 Ensures that the objects retrieved have the CKA_X_TRUST flag.
259 This is p11-kit trust module extension, thus this flag is only
260 valid with p11-kit registered trust modules.
261 --mark-decrypt, --no-mark-decrypt
263 Marks the object to be written for decryption. The
264 no-mark-decrypt form will disable the option.
265 Marks the object to be generated/written with the CKA_DECRYPT
267 flag set to true.
268 --mark-sign, --no-mark-sign
270 Marks the object to be written for signature generation. The
271 no-mark-sign form will disable the option.
272 Marks the object to be generated/written with the CKA_SIGN flag
274 set to true.
275 --mark-ca, --no-mark-ca
277 Marks the object to be written as a CA. The no-mark-ca form
278 will disable the option.
279 Marks the object to be generated/written with the CKA_CERTIFI‐
281 CATE_CATEGORY as CA.
282 --mark-private, --no-mark-private
284 Marks the object to be written as private. The no-mark-private
285 form will disable the option.
286 Marks the object to be generated/written with the CKA_PRIVATE
288 flag. The written object will require a PIN to be used.
289 --ca This is an alias for the --mark-ca option.
291 --private
293 This is an alias for the --mark-private option.
294 --secret-key=string
296 Provide a hex encoded secret key.
297 This secret key will be written to the module if --write is
299 specified.
300 --load-privkey=file
302 Private key file to use.
303 --load-pubkey=file
306 Public key file to use.
307 --load-certificate=file
310 Certificate file to use.
311 Other options
314 -d number, --debug=number
315 Enable debugging. This option takes an integer number as its
316 argument. The value of number is constrained to being:
317 in the range 0 through 9999
318 Specifies the debug level.
320 --outfile=string
322 Output file.
323 --login, --no-login
326 Force (user) login to token. The no-login form will disable the
327 option.
328 --so-login, --no-so-login
331 Force security officer login to token. The no-so-login form
332 will disable the option.
333 Forces login to the token as security officer (admin).
335 --admin-login
337 This is an alias for the --so-login option.
338 --test-sign
340 Tests the signature operation of the provided object.
341 It can be used to test the correct operation of the signature
343 operation. If both a private and a public key are available
344 this operation will sign and verify the signed data.
345 --sign-params=string
347 Sign with a specific signature algorithm.
348 This option can be combined with --test-sign, to sign with a
350 specific signature algorithm variant. The only option supported
351 is 'RSA-PSS', and should be specified in order to use RSA-PSS
352 signature on RSA keys.
353 --hash=string
355 Hash algorithm to use for signing.
356 This option can be combined with test-sign. Available hash func‐
358 tions are SHA1, RMD160, SHA256, SHA384, SHA512, SHA3-224,
359 SHA3-256, SHA3-384, SHA3-512.
360 --generate-random=number
362 Generate random data. This option takes an integer number as
363 its argument.
364 Asks the token to generate a number of bytes of random bytes.
366 -8, --pkcs8
368 Use PKCS #8 format for private keys.
369 --inder, --no-inder
372 Use DER/RAW format for input. The no-inder form will disable
373 the option.
374 Use DER/RAW format for input certificates and private keys.
376 --inraw
378 This is an alias for the --inder option.
379 --outder, --no-outder
381 Use DER format for output certificates, private keys, and DH
382 parameters. The no-outder form will disable the option.
383 The output will be in DER or RAW format.
385 --outraw
387 This is an alias for the --outder option.
388 --provider=file
390 Specify the PKCS #11 provider library.
391 This will override the default options in
393 /etc/gnutls/pkcs11.conf
394 --provider-opts=string
396 Specify parameters for the PKCS #11 provider library.
397 This is a PKCS#11 internal option used by few modules.
399 Mainly for testing PKCS#11 modules.
400 NOTE: THIS OPTION IS DEPRECATED
402 --detailed-url, --no-detailed-url
404 Print detailed URLs. The no-detailed-url form will disable the
405 option.
406 --only-urls
409 Print a compact listing using only the URLs.
410 --batch
413 Disable all interaction with the tool.
414 In batch mode there will be no prompts, all parameters need to
416 be specified on command line.
417 -h, --help
419 Display usage information and exit.
420 -!, --more-help
422 Pass the extended usage information through a pager.
423 -v [{v|c|n --version [{v|c|n}]}]
425 Output version of program and exit. The default mode is `v', a
426 simple version. The `c' mode will print copyright information
427 and `n' will print the full copyright notice.
428
430 To view all tokens in your system use:
431 $ p11tool --list-tokens
432 To view all objects in a token use:
434 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
435 To store a private key and a certificate in a token run:
437 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem --label "Mykey"
438 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem --label "Mykey"
439 Note that some tokens require the same label to be used for the cer‐
440 tificate and its corresponding private key.
441 To generate an RSA private key inside the token use:
443 $ p11tool --login --generate-privkey rsa --bits 1024 --label "MyNewKey" --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
444 The bits parameter in the above example is explicitly set because some
445 tokens only support limited choices in the bit length. The output file
446 is the corresponding public key. This key can be used to general a cer‐
447 tificate request with certtool.
448 certtool --generate-request --load-privkey "pkcs11:KEY-URL" --load-pubkey MyNewKey.pub --outfile request.pem
449
452 One of the following exit values will be returned:
453 0 (EXIT_SUCCESS)
455 Successful program execution.
456 1 (EXIT_FAILURE)
458 The operation failed or the command syntax was not valid.
459 70 (EX_SOFTWARE)
461 libopts had an internal operational error. Please report it to
462 autogen-users@lists.sourceforge.net. Thank you.
463
465 certtool (1)
466
468 Nikos Mavrogiannopoulos, Simon Josefsson and others; see
469 /usr/share/doc/gnutls/AUTHORS for a complete list.
470
472 Copyright (C) 2000-2020 Free Software Foundation, and others all rights
473 reserved. This program is released under the terms of the GNU General
474 Public License, version 3 or later.
475
477 Please send bug reports to: bugs@gnutls.org
478
480 This manual page was AutoGen-erated from the p11tool option defini‐
481 tions.
4823.6.15 04 Sep 2020 p11tool(1)