1 @node p11tool Invocation
2 @subsection Invoking p11tool
5 # -*- buffer-read-only: t -*- vi: set ro:
7 # DO NOT EDIT THIS FILE (invoke-p11tool.texi)
9 # It has been AutoGen-ed June 26, 2014 at 08:12:19 PM by AutoGen 5.18.2
10 # From the definitions ../src/p11tool-args.def
11 # and the template file agtexi-cmd.tpl
15 Program that allows operations on PKCS #11 smart cards
18 To use PKCS #11 tokens with GnuTLS the p11-kit configuration files need to be setup.
19 That is create a .module file in /etc/pkcs11/modules with the contents 'module: /path/to/pkcs11.so'.
20 Alternatively the configuration file /etc/gnutls/pkcs11.conf has to exist and contain a number
21 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 environment variable
27 This section was generated by @strong{AutoGen},
28 using the @code{agtexi-cmd} template and the option descriptions for the @code{p11tool} program.
29 This software is released under the GNU General Public License, version 3 or later.
32 @anchor{p11tool usage}
33 @subsubheading p11tool help/usage (@option{--help})
36 This is the automatically generated usage text for p11tool.
38 The text printed is the same whether selected with the @code{help} option
39 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
40 the usage text by passing it through a pager program.
41 @code{more-help} is disabled on platforms without a working
42 @code{fork(2)} function. The @code{PAGER} environment variable is
43 used to select the program, defaulting to @file{more}. Both will exit
44 with a status code of 0.
48 p11tool - GnuTLS PKCS #11 tool
49 Usage: p11tool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [url]
51 -d, --debug=num Enable debugging
52 - it must be in the range:
54 --outfile=str Output file
55 --list-tokens List all available tokens
56 --export Export the object specified by the URL
57 --export-chain Export the certificate specified by the URL and its chain of trust
58 --list-mechanisms List all available mechanisms in a token
59 --list-all List all available objects in a token
60 --list-all-certs List all available certificates in a token
61 --list-certs List all certificates that have an associated private key
62 --list-all-privkeys List all available private keys in a token
63 --list-privkeys an alias for the 'list-all-privkeys' option
64 --list-keys an alias for the 'list-all-privkeys' option
65 --list-all-trusted List all available certificates marked as trusted
66 --initialize Initializes a PKCS #11 token
67 --write Writes the loaded objects to a PKCS #11 token
68 --delete Deletes the objects matching the PKCS #11 URL
69 --generate-random=num Generate random data
70 --generate-rsa Generate an RSA private-public key pair
71 --generate-dsa Generate an RSA private-public key pair
72 --generate-ecc Generate an RSA private-public key pair
73 --label=str Sets a label for the write operation
74 --trusted Marks the object to be written as trusted
75 - disabled as '--no-trusted'
76 --private Marks the object to be written as private
77 - disabled as '--no-private'
79 --login Force (user) login to token
80 - disabled as '--no-login'
81 --so-login Force security officer login to token
82 - disabled as '--no-so-login'
83 --admin-login an alias for the 'so-login' option
84 --detailed-url Print detailed URLs
85 - disabled as '--no-detailed-url'
86 --secret-key=str Provide a hex encoded secret key
87 --load-privkey=file Private key file to use
89 --load-pubkey=file Public key file to use
91 --load-certificate=file Certificate file to use
93 -8, --pkcs8 Use PKCS #8 format for private keys
94 --bits=num Specify the number of bits for key generate
95 --sec-param=str Specify the security level
96 --inder Use DER/RAW format for input
97 - disabled as '--no-inder'
98 --inraw an alias for the 'inder' option
99 --outder Use DER format for output certificates, private keys, and DH parameters
100 - disabled as '--no-outder'
101 --outraw an alias for the 'outder' option
102 --provider=file Specify the PKCS #11 provider library
103 - file must pre-exist
104 -v, --version[=arg] output version information and exit
105 -h, --help display extended usage information and exit
106 -!, --more-help extended usage information passed thru pager
108 Options are specified by doubled hyphens and their name or by a single
109 hyphen and the flag character.
110 Operands and options may be intermixed. They will be reordered.
112 Program that allows handling data from PKCS #11 smart cards and security
115 To use PKCS #11 tokens with gnutls the configuration file
116 /etc/gnutls/pkcs11.conf has to exist and contain a number of lines of the
117 form 'load=/usr/lib/opensc-pkcs11.so'. Alternatively the p11-kit
118 configuration files have to be setup.
120 To provide the PIN for all the operations below use the environment
126 @anchor{p11tool debug}
127 @subsubheading debug option (-d)
129 This is the ``enable debugging'' option.
130 This option takes a number argument.
131 Specifies the debug level.
132 @anchor{p11tool export-chain}
133 @subsubheading export-chain option
135 This is the ``export the certificate specified by the url and its chain of trust'' option.
136 Exports the certificate specified by the URL and generates its chain of trust based on the stored certificates in the module.
137 @anchor{p11tool list-all-privkeys}
138 @subsubheading list-all-privkeys option
140 This is the ``list all available private keys in a token'' option.
141 Lists all the private keys in a token that match the specified URL.
142 @anchor{p11tool list-privkeys}
143 @subsubheading list-privkeys option
145 This is an alias for the @code{list-all-privkeys} option,
146 @pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}.
148 @anchor{p11tool list-keys}
149 @subsubheading list-keys option
151 This is an alias for the @code{list-all-privkeys} option,
152 @pxref{p11tool list-all-privkeys, the list-all-privkeys option documentation}.
154 @anchor{p11tool write}
155 @subsubheading write option
157 This is the ``writes the loaded objects to a pkcs #11 token'' option.
158 It can be used to write private keys, certificates or secret keys to a token.
159 @anchor{p11tool generate-random}
160 @subsubheading generate-random option
162 This is the ``generate random data'' option.
163 This option takes a number argument.
164 Asks the token to generate a number of bytes of random bytes.
165 @anchor{p11tool generate-rsa}
166 @subsubheading generate-rsa option
168 This is the ``generate an rsa private-public key pair'' option.
169 Generates an RSA private-public key pair on the specified token.
170 @anchor{p11tool generate-dsa}
171 @subsubheading generate-dsa option
173 This is the ``generate an rsa private-public key pair'' option.
174 Generates an RSA private-public key pair on the specified token.
175 @anchor{p11tool generate-ecc}
176 @subsubheading generate-ecc option
178 This is the ``generate an rsa private-public key pair'' option.
179 Generates an RSA private-public key pair on the specified token.
180 @anchor{p11tool private}
181 @subsubheading private option
183 This is the ``marks the object to be written as private'' option.
186 This option has some usage constraints. It:
189 can be disabled with --no-private.
191 It is enabled by default.
194 The written object will require a PIN to be used.
195 @anchor{p11tool so-login}
196 @subsubheading so-login option
198 This is the ``force security officer login to token'' option.
201 This option has some usage constraints. It:
204 can be disabled with --no-so-login.
207 Forces login to the token as security officer (admin).
208 @anchor{p11tool admin-login}
209 @subsubheading admin-login option
211 This is an alias for the @code{so-login} option,
212 @pxref{p11tool so-login, the so-login option documentation}.
214 @anchor{p11tool sec-param}
215 @subsubheading sec-param option
217 This is the ``specify the security level'' option.
218 This option takes a string argument @file{Security parameter}.
219 This is alternative to the bits option. Available options are [low, legacy, medium, high, ultra].
220 @anchor{p11tool inder}
221 @subsubheading inder option
223 This is the ``use der/raw format for input'' option.
226 This option has some usage constraints. It:
229 can be disabled with --no-inder.
232 Use DER/RAW format for input certificates and private keys.
233 @anchor{p11tool inraw}
234 @subsubheading inraw option
236 This is an alias for the @code{inder} option,
237 @pxref{p11tool inder, the inder option documentation}.
239 @anchor{p11tool outder}
240 @subsubheading outder option
242 This is the ``use der format for output certificates, private keys, and dh parameters'' option.
245 This option has some usage constraints. It:
248 can be disabled with --no-outder.
251 The output will be in DER or RAW format.
252 @anchor{p11tool outraw}
253 @subsubheading outraw option
255 This is an alias for the @code{outder} option,
256 @pxref{p11tool outder, the outder option documentation}.
258 @anchor{p11tool provider}
259 @subsubheading provider option
261 This is the ``specify the pkcs #11 provider library'' option.
262 This option takes a file argument.
263 This will override the default options in /etc/gnutls/pkcs11.conf
264 @anchor{p11tool exit status}
265 @subsubheading p11tool exit status
267 One of the following exit values will be returned:
269 @item 0 (EXIT_SUCCESS)
270 Successful program execution.
271 @item 1 (EXIT_FAILURE)
272 The operation failed or the command syntax was not valid.
274 @anchor{p11tool See Also}
275 @subsubheading p11tool See Also
277 @anchor{p11tool Examples}
278 @subsubheading p11tool Examples
279 To view all tokens in your system use:
281 $ p11tool --list-tokens
284 To view all objects in a token use:
286 $ p11tool --login --list-all "pkcs11:TOKEN-URL"
289 To store a private key and a certificate in a token run:
291 $ p11tool --login --write "pkcs11:URL" --load-privkey key.pem \
293 $ p11tool --login --write "pkcs11:URL" --load-certificate cert.pem \
296 Note that some tokens require the same label to be used for the certificate
297 and its corresponding private key.
299 To generate an RSA private key inside the token use:
301 $ p11tool --login --generate-rsa --bits 1024 --label "MyNewKey" \
302 --outfile MyNewKey.pub "pkcs11:TOKEN-URL"
304 The bits parameter in the above example is explicitly set because some
305 tokens only support limited choices in the bit length. The output file is the
306 corresponding public key. This key can be used to general a certificate
307 request with certtool.
309 certtool --generate-request --load-privkey "pkcs11:KEY-URL" \
310 --load-pubkey MyNewKey.pub --outfile request.pem