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

DESCRIPTION

14       Program  that  allows  operations  on PKCS #11 smart cards and security
15       modules.
16
17       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
23       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
26

OPTIONS

28   Tokens
29       --list-tokens
30              List all available tokens.
31
32
33       --list-token-urls
34              List the URLs available tokens.
35
36              This is a more compact version of --list-tokens.
37
38       --list-mechanisms
39              List all available mechanisms in a token.
40
41
42       --initialize
43              Initializes a PKCS #11 token.
44
45
46       --initialize-pin
47              Initializes/Resets a PKCS #11 token user PIN.
48
49
50       --initialize-so-pin
51              Initializes/Resets a PKCS #11 token security officer PIN.
52
53              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
57       --set-pin=str
58              Specify the PIN to use on token operations.
59
60              Alternatively the GNUTLS_PIN environment variable may be used.
61
62       --set-so-pin=str
63              Specify  the  Security Officer's PIN to use on token initializa‐
64              tion.
65
66              Alternatively the  GNUTLS_SO_PIN  environment  variable  may  be
67              used.
68
69   Object listing
70       --list-all
71              List all available objects in a token.
72
73              All objects available in the token will be listed. That includes
74              objects which are potentially unaccessible using this tool.
75
76       --list-all-certs
77              List all available certificates in a token.
78
79              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
83       --list-certs
84              List all certificates that have an associated private key.
85
86              That option will only display certificates which have a  private
87              key associated with them (share the same ID).
88
89       --list-all-privkeys
90              List all available private keys in a token.
91
92              Lists  all  the private keys in a token that match the specified
93              URL.
94
95       --list-privkeys
96              This is an alias for the --list-all-privkeys option.
97
98       --list-keys
99              This is an alias for the --list-all-privkeys option.
100
101       --list-all-trusted
102              List all available certificates marked as trusted.
103
104
105       --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
110
111       --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
116              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
121       --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
126              Exports  the  certificate specified by the URL and generates its
127              chain of trust based on the stored certificates in the module.
128
129       --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
134              Exports the public key for the specified private key
135
136       --info List information on an available object in a token.
137
138
139       --trusted
140              This is an alias for the --mark-trusted option.
141
142       --distrusted
143              This is an alias for the --mark-distrusted option.
144
145   Key generation
146       --generate-privkey=str
147              Generate private-public key pair of given type.
148
149              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
153       --generate-rsa
154              Generate an RSA private-public key pair.
155
156              Generates an RSA private-public key pair on the specified token.
157              Should be combined with --sec-param or --bits.
158
159              NOTE: THIS OPTION IS DEPRECATED
160
161       --generate-dsa
162              Generate a DSA private-public key pair.
163
164              Generates  a DSA private-public key pair on the specified token.
165              Should be combined with --sec-param or --bits.
166
167              NOTE: THIS OPTION IS DEPRECATED
168
169       --generate-ecc
170              Generate an ECDSA private-public key pair.
171
172              Generates an ECDSA private-public key pair on the specified  to‐
173              ken.  Should be combined with --curve, --sec-param or --bits.
174
175              NOTE: THIS OPTION IS DEPRECATED
176
177       --bits=num
178              Specify  the  number  of bits for the key generate.  This option
179              takes an integer number as its argument.
180
181              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
186       --curve=str
187              Specify the curve used for EC key generation.
188
189              Supported  values are secp192r1, secp224r1, secp256r1, secp384r1
190              and secp521r1.
191
192       --sec-param=security parameter
193              Specify the security level.
194
195              This is alternative to the bits option.  Available  options  are
196              [low, legacy, medium, high, ultra].
197
198   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
204              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
208       --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
213              Modifies  or  sets the CKA_LABEL in the specified by the URL ob‐
214              ject
215
216       --write
217              Writes the loaded objects to a PKCS #11 token.
218
219              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
223              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
229       --delete
230              Deletes the objects matching the given PKCS #11 URL.
231
232
233       --label=str
234              Sets a label for the write operation.
235
236
237       --id=str
238              Sets an ID for the write operation.
239
240              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
243       --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
247              Marks the generated key with the CKA_WRAP flag.
248
249       --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
254              Marks the object to  be  generated/written  with  the  CKA_TRUST
255              flag.
256
257       --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
262              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
266       --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
270              Marks the object to be generated/written  with  the  CKA_DECRYPT
271              flag set to true.
272
273       --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
277              Marks the object to be generated/written with the CKA_SIGN  flag
278              set to true.
279
280       --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
284              Marks the object to be generated/written with  the  CKA_CERTIFI‐
285              CATE_CATEGORY as CA.
286
287       --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
291              Marks the object to be generated/written  with  the  CKA_PRIVATE
292              flag. The written object will require a PIN to be used.
293
294       --ca   This is an alias for the --mark-ca option.
295
296       --private
297              This is an alias for the --mark-private option.
298
299       --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
303              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
307       --secret-key=str
308              Provide a hex encoded secret key.
309
310              This secret key will be written to  the  module  if  --write  is
311              specified.
312
313       --load-privkey=file
314              Private key file to use.
315
316
317       --load-pubkey=file
318              Public key file to use.
319
320
321       --load-certificate=file
322              Certificate file to use.
323
324
325   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
331              Specifies the debug level.
332
333       --outfile=str
334              Output file.
335
336
337       --login, --no-login
338              Force (user) login to token.  The no-login form will disable the
339              option.
340
341
342       --so-login, --no-so-login
343              Force security officer login to token.  The no-so-login form
344              will disable the option.
345
346              Forces login to the token as security officer (admin).
347
348       --admin-login
349              This is an alias for the --so-login option.
350
351       --test-sign
352              Tests the signature operation of the provided object.
353
354              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
358       --sign-params=str
359              Sign with a specific signature algorithm.
360
361              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
366       --hash=str
367              Hash algorithm to use for signing.
368
369              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
373       --generate-random=num
374              Generate random data.  This option takes an integer number as
375              its argument.
376
377              Asks the token to generate a number of bytes of random bytes.
378
379       -8, --pkcs8
380              Use PKCS #8 format for private keys.
381
382
383       --inder, --no-inder
384              Use DER/RAW format for input.  The no-inder form will disable
385              the option.
386
387              Use DER/RAW format for input certificates and private keys.
388
389       --inraw
390              This is an alias for the --inder option.
391
392       --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
396              The output will be in DER or RAW format.
397
398       --outraw
399              This is an alias for the --outder option.
400
401       --provider=file
402              Specify the PKCS #11 provider library.
403
404              This will override the default options in
405              /etc/gnutls/pkcs11.conf
406
407       --provider-opts=str
408              Specify parameters for the PKCS #11 provider library.
409
410              This is a PKCS#11 internal option used by few modules.
411                  Mainly for testing PKCS#11 modules.
412
413              NOTE: THIS OPTION IS DEPRECATED
414
415       --detailed-url, --no-detailed-url
416              Print detailed URLs.  The no-detailed-url form will disable the
417              option.
418
419
420       --only-urls
421              Print a compact listing using only the URLs.
422
423
424       --batch
425              Disable all interaction with the tool.
426
427              In batch mode there will be no prompts, all parameters need to
428              be specified on command line.
429
430       -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
435       -h, --help
436              Display usage information and exit.
437
438       -!, --more-help
439              Pass the extended usage information through a pager.
440
441
442

EXAMPLES

444       To view all tokens in your system use:
445           $ p11tool --list-tokens
446
447       To view all objects in a token use:
448           $ p11tool --login --list-all "pkcs11:TOKEN-URL"
449
450       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
456       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

EXIT STATUS

465       One of the following exit values will be returned:
466
467       0  (EXIT_SUCCESS)
468              Successful program execution.
469
470       1  (EXIT_FAILURE)
471              The operation failed or the command syntax was not valid.
472

SEE ALSO

474       certtool (1)
475

AUTHORS

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

BUGS

483       Please send bug reports to: bugs@gnutls.org
484
485
486
4873.8.2                             15 Nov 2023                       p11tool(1)
Impressum