1p11tool(1) User Commands p11tool(1)
2
3
4
6 p11tool - GnuTLS PKCS #11 tool
7
9 p11tool [-flags] [-flag [value]] [--option-name[[=| ]value]] [url]
10
11 Operands and options may be intermixed. They will be reordered.
12
13
15 Program that allows operations on PKCS #11 smart cards and security
16 modules.
17
18 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
24 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
27
29 Tokens
30 --list-tokens
31 List all available tokens.
32
33
34 --list-token-urls
35 List the URLs available tokens.
36
37 This is a more compact version of --list-tokens.
38
39 --list-mechanisms
40 List all available mechanisms in a token.
41
42
43 --initialize
44 Initializes a PKCS #11 token.
45
46
47 --initialize-pin
48 Initializes/Resets a PKCS #11 token user PIN.
49
50
51 --initialize-so-pin
52 Initializes/Resets a PKCS #11 token security officer PIN..
53
54 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
58 --set-pin=string
59 Specify the PIN to use on token operations.
60
61 Alternatively the GNUTLS_PIN environment variable may be used.
62
63 --set-so-pin=string
64 Specify the Security Officer's PIN to use on token initializa‐
65 tion.
66
67 Alternatively the GNUTLS_SO_PIN environment variable may be
68 used.
69
70 Object listing
71 --list-all
72 List all available objects in a token.
73
74 All objects available in the token will be listed. That includes
75 objects which are potentially unaccessible using this tool.
76
77 --list-all-certs
78 List all available certificates in a token.
79
80 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
84 --list-certs
85 List all certificates that have an associated private key.
86
87 That option will only display certificates which have a private
88 key associated with them (share the same ID).
89
90 --list-all-privkeys
91 List all available private keys in a token.
92
93 Lists all the private keys in a token that match the specified
94 URL.
95
96 --list-privkeys
97 This is an alias for the --list-all-privkeys option.
98
99 --list-keys
100 This is an alias for the --list-all-privkeys option.
101
102 --list-all-trusted
103 List all available certificates marked as trusted.
104
105
106 --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
111
112 --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
117 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
122 --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
127 Exports the certificate specified by the URL and generates its
128 chain of trust based on the stored certificates in the module.
129
130 --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
135 Exports the public key for the specified private key
136
137 --info List information on an available object in a token.
138
139
140 --trusted
141 This is an alias for the --mark-trusted option.
142
143 --distrusted
144 This is an alias for the --mark-distrusted option.
145
146 Key generation
147 --generate-privkey=string
148 Generate private-public key pair of given type.
149
150 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
154 --generate-rsa
155 Generate an RSA private-public key pair.
156
157 Generates an RSA private-public key pair on the specified token.
158 Should be combined with --sec-param or --bits.
159
160 NOTE: THIS OPTION IS DEPRECATED
161
162 --generate-dsa
163 Generate a DSA private-public key pair.
164
165 Generates a DSA private-public key pair on the specified token.
166 Should be combined with --sec-param or --bits.
167
168 NOTE: THIS OPTION IS DEPRECATED
169
170 --generate-ecc
171 Generate an ECDSA private-public key pair.
172
173 Generates an ECDSA private-public key pair on the specified
174 token. Should be combined with --curve, --sec-param or --bits.
175
176 NOTE: THIS OPTION IS DEPRECATED
177
178 --bits=number
179 Specify the number of bits for the key generate. This option
180 takes an integer number as its argument.
181
182 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
187 --curve=string
188 Specify the curve used for EC key generation.
189
190 Supported values are secp192r1, secp224r1, secp256r1, secp384r1
191 and secp521r1.
192
193 --sec-param=security parameter
194 Specify the security level.
195
196 This is alternative to the bits option. Available options are
197 [low, legacy, medium, high, ultra].
198
199 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
205 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
209 --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
214 Modifies or sets the CKA_LABEL in the specified by the URL
215 object
216
217 --write
218 Writes the loaded objects to a PKCS #11 token.
219
220 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
225 --delete
226 Deletes the objects matching the given PKCS #11 URL.
227
228
229 --label=string
230 Sets a label for the write operation.
231
232
233 --id=string
234 Sets an ID for the write operation.
235
236 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
239 --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
243 Marks the generated key with the CKA_WRAP flag.
244
245 --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
250 Marks the object to be generated/written with the CKA_TRUST
251 flag.
252
253 --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
258 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
262 --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
266 Marks the object to be generated/written with the CKA_DECRYPT
267 flag set to true.
268
269 --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
273 Marks the object to be generated/written with the CKA_SIGN flag
274 set to true.
275
276 --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
280 Marks the object to be generated/written with the CKA_CERTIFI‐
281 CATE_CATEGORY as CA.
282
283 --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
287 Marks the object to be generated/written with the CKA_PRIVATE
288 flag. The written object will require a PIN to be used.
289
290 --ca This is an alias for the --mark-ca option.
291
292 --private
293 This is an alias for the --mark-private option.
294
295 --secret-key=string
296 Provide a hex encoded secret key.
297
298 This secret key will be written to the module if --write is
299 specified.
300
301 --load-privkey=file
302 Private key file to use.
303
304
305 --load-pubkey=file
306 Public key file to use.
307
308
309 --load-certificate=file
310 Certificate file to use.
311
312
313 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
319 Specifies the debug level.
320
321 --outfile=string
322 Output file.
323
324
325 --login, --no-login
326 Force (user) login to token. The no-login form will disable the
327 option.
328
329
330 --so-login, --no-so-login
331 Force security officer login to token. The no-so-login form
332 will disable the option.
333
334 Forces login to the token as security officer (admin).
335
336 --admin-login
337 This is an alias for the --so-login option.
338
339 --test-sign
340 Tests the signature operation of the provided object.
341
342 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
346 --sign-params=string
347 Sign with a specific signature algorithm.
348
349 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
354 --hash=string
355 Hash algorithm to use for signing.
356
357 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
361 --generate-random=number
362 Generate random data. This option takes an integer number as
363 its argument.
364
365 Asks the token to generate a number of bytes of random bytes.
366
367 -8, --pkcs8
368 Use PKCS #8 format for private keys.
369
370
371 --inder, --no-inder
372 Use DER/RAW format for input. The no-inder form will disable
373 the option.
374
375 Use DER/RAW format for input certificates and private keys.
376
377 --inraw
378 This is an alias for the --inder option.
379
380 --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
384 The output will be in DER or RAW format.
385
386 --outraw
387 This is an alias for the --outder option.
388
389 --provider=file
390 Specify the PKCS #11 provider library.
391
392 This will override the default options in
393 /etc/gnutls/pkcs11.conf
394
395 --provider-opts=string
396 Specify parameters for the PKCS #11 provider library.
397
398 This is a PKCS#11 internal option used by few modules.
399 Mainly for testing PKCS#11 modules.
400
401 NOTE: THIS OPTION IS DEPRECATED
402
403 --detailed-url, --no-detailed-url
404 Print detailed URLs. The no-detailed-url form will disable the
405 option.
406
407
408 --only-urls
409 Print a compact listing using only the URLs.
410
411
412 --batch
413 Disable all interaction with the tool.
414
415 In batch mode there will be no prompts, all parameters need to
416 be specified on command line.
417
418 -h, --help
419 Display usage information and exit.
420
421 -!, --more-help
422 Pass the extended usage information through a pager.
423
424 -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
433 To view all objects in a token use:
434 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
435
436 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
442 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
450
452 One of the following exit values will be returned:
453
454 0 (EXIT_SUCCESS)
455 Successful program execution.
456
457 1 (EXIT_FAILURE)
458 The operation failed or the command syntax was not valid.
459
460 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-2018 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.
482
483
484
4853.6.4 30 Nov 2018 p11tool(1)