1p11tool(1)                       User Commands                      p11tool(1)
2
3
4

NAME

6       p11tool - GnuTLS PKCS #11 tool
7

SYNOPSIS

9       p11tool [-flags] [-flag [value]] [--option-name[[=| ]value]] [url]
10
11       Operands and options may be intermixed.  They will be reordered.
12
13

DESCRIPTION

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

OPTIONS

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

EXAMPLES

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

EXIT STATUS

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

SEE ALSO

465           certtool (1)
466

AUTHORS

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

BUGS

477       Please send bug reports to: bugs@gnutls.org
478

NOTES

480       This manual page was AutoGen-erated from the p11tool option defini‐
481       tions.
482
483
484
4853.6.15                            04 Sep 2020                       p11tool(1)
Impressum