1PKCS11-TOOL(1)                   OpenSC Tools                   PKCS11-TOOL(1)
2
3
4

NAME

6       pkcs11-tool - utility for managing and using PKCS #11 security tokens
7

SYNOPSIS

9       pkcs11-tool [OPTIONS]
10

DESCRIPTION

12       The pkcs11-tool utility is used to manage the data objects on smart
13       cards and similar PKCS #11 security tokens. Users can list and read
14       PINs, keys and certificates stored on the token. User PIN
15       authentication is performed for those operations that require it.
16

OPTIONS

18       --attr-from filename
19           Extract information from filename (DER-encoded certificate file)
20           and create the corresponding attributes when writing an object to
21           the token. Example: the certificate subject name is used to create
22           the CKA_SUBJECT attribute.
23
24       --change-pin, -c
25           Change the user PIN on the token
26
27       --unlock-pin
28           Unlock User PIN (without --login unlock in logged in session;
29           otherwise --login-type has to be 'context-specific').
30
31       --hash, -h
32           Hash some data.
33
34       --hash-algorithm mechanism
35           Specify hash algorithm used with RSA-PKCS-PSS signature or RSA-OAEP
36           decryption. Allowed values are "SHA-1", "SHA256", "SHA384",
37           "SHA512", and some tokens may also allow "SHA224". Default is
38           "SHA-1".
39
40           Note that the input to RSA-PKCS-PSS has to be of the size equal to
41           the specified hash algorithm. E.g., for SHA256 the signature input
42           must be exactly 32 bytes long (for mechanisms SHA256-RSA-PKCS-PSS
43           there is no such restriction). For RSA-OAEP, the plaintext input
44           size mLen must be at most keyLen - 2 - 2*hashLen. For example, for
45           RSA 3072-bit key and SHA384, the longest plaintext to encrypt with
46           RSA-OAEP is (with all sizes in bytes): 384 - 2 - 2*48 = 286, aka
47           286 bytes.
48
49       --id id, -d id
50           Specify the id of the object to operate on.
51
52       --init-pin
53           Initializes the user PIN. This option differs from --change-pin in
54           that it sets the user PIN for the first time. Once set, the user
55           PIN can be changed using --change-pin.
56
57       --init-token
58           Initialize a token: set the token label as well as a Security
59           Officer PIN (the label must be specified using --label).
60
61       --input-file filename, -i filename
62           Specify the path to a file for input.
63
64       --keypairgen, -k
65           Generate a new key pair (public and private pair.)
66
67       --keygen
68           Generate a new key.
69
70       --key-type specification
71           Specify the type and length of the key to create, for example
72           rsa:1024 or EC:prime256v1.
73
74       --usage-sign
75           Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in
76           pubkey).
77
78       --usage-decrypt
79           Specify 'decrypt' key usage flag (RSA only, set DECRYPT privkey,
80           ENCRYPT in pubkey).
81
82       --usage-derive
83           Specify 'derive' key usage flag (EC only).
84
85       --label name, -a name
86           Specify the name of the object to operate on (or the token label
87           when --init-token is used).
88
89       --list-mechanisms, -M
90           Display a list of mechanisms supported by the token.
91
92       --list-objects, -O
93           Display a list of objects.
94
95       --list-slots, -L
96           Display a list of available slots on the token.
97
98       --list-token-slots, -T
99           List slots with tokens.
100
101       --login, -l
102           Authenticate to the token before performing other operations. This
103           option is not needed if a PIN is provided on the command line.
104
105       --login-type
106           Specify login type ('so', 'user', 'context-specific';
107           default:'user').
108
109       --mechanism mechanism, -m mechanism
110           Use the specified mechanism for token operations. See -M for a list
111           of mechanisms supported by your token. The mechanism can also be
112           specified in hexadecimal, e.g., 0x80001234.
113
114       --mgf function
115           Use the specified Message Generation Function (MGF) function for
116           RSA-PKCS-PSS signatures or RSA-OAEP decryptions. Supported
117           arguments are MGF1-SHA1 to MGF1-SHA512 if supported by the driver.
118           The default is based on the hash selection.
119
120       --module mod
121           Specify a PKCS#11 module (or library) to load.
122
123       --moz-cert filename, -z filename
124           Test a Mozilla-like keypair generation and certificate request.
125           Specify the filename to the certificate file.
126
127       --output-file filename, -o filename
128           Specify the path to a file for output.
129
130       --pin pin, -p pin
131           Use the given pin for token operations. If set to env:VARIABLE, the
132           value of the environment variable VARIABLE is used. WARNING: Be
133           careful using this option as other users may be able to read the
134           command line from the system or if it is embedded in a script. If
135           set to env:VARIABLE, the value of the environment variable VARIABLE
136           is used.
137
138           This option will also set the --login option.
139
140       --puk puk
141           Supply User PUK on the command line.
142
143       --new-pin pin
144           Supply new User PIN on the command line.
145
146       --sensitive
147           Set the CKA_SENSITIVE attribute (object cannot be revealed in
148           plaintext).
149
150       --set-id id, -e id
151           Set the CKA_ID of the object.
152
153       --show-info, -I
154           Display general token information.
155
156       --sign, -s
157           Sign some data.
158
159       --decrypt,
160           Decrypt some data.
161
162       --derive,
163           Derive a secret key using another key and some data.
164
165       --derive-pass-der,
166           Derive ECDHpass DER encoded pubkey for compatibility with some
167           PKCS#11 implementations
168
169       --salt-len bytes
170           Specify how many bytes of salt should be used in RSA-PSS
171           signatures. Accepts two special values: "-1" means salt length
172           equals to digest length, "-2" means use maximum permissible length.
173           Default is digest length (-1).
174
175       --slot id
176           Specify the id of the slot to use.
177
178       --slot-description description
179           Specify the description of the slot to use.
180
181       --slot-index index
182           Specify the index of the slot to use.
183
184       --token-label label
185           Specify the label of token. Will be used the first slot, that has
186           the inserted token with this label.
187
188       --so-pin pin
189           Use the given pin as the Security Officer PIN for some token
190           operations (token initialization, user PIN initialization, etc). If
191           set to env:VARIABLE, the value of the environment variable VARIABLE
192           is used. The same warning as --pin also applies here.
193
194       --test, -t
195           Perform some tests on the token. This option is most useful when
196           used with either --login or --pin.
197
198       --test-hotplug
199           Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
200
201       --private
202           Set the CKA_PRIVATE attribute (object is only viewable after a
203           login).
204
205       --test-ec
206           Test EC (best used with the --login or --pin option).
207
208       --test-fork
209           Test forking and calling C_Initialize() in the child.
210
211       --type type, -y type
212           Specify the type of object to operate on. Examples are cert,
213           privkey and pubkey.
214
215       --verbose, -v
216           Cause pkcs11-tool to be more verbose.
217
218           NB! This does not affect OpenSC debugging level! To set OpenSC
219           PKCS#11 module into debug mode, set the OPENSC_DEBUG environment
220           variable to a non-zero number.
221
222       --verify,
223           Verify signature of some data.
224
225       --read-object, -r
226           Get object's CKA_VALUE attribute (use with --type).
227
228       --delete-object, -b
229           Delete an object.
230
231       --application-label label
232           Specify the application label of the data object (use with --type
233           data).
234
235       --application-id id
236           Specify the application ID of the data object (use with --type
237           data).
238
239       --issuer data
240           Specify the issuer in hexadecimal format (use with --type cert).
241
242       --subject data
243           Specify the subject in hexadecimal format (use with --type
244           cert/privkey/pubkey).
245
246       --signature-file filename
247           The path to the signature file for signature verification
248
249       --signature-format format
250           Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
251
252       --write-object filename, -w filename
253           Write a key or certificate object to the token.  filename points to
254           the DER-encoded certificate or key file.
255
256       --generate-random num
257           Get num bytes of random data.
258

EXAMPLES

260       To list all certificates on the smart card:
261
262           pkcs11-tool --list-objects --type cert
263
264       To read the certificate with ID KEY_ID in DER format from smart card:
265
266           pkcs11-tool --read-object  --id KEY_ID --type cert --output-file cert.der
267
268       To convert the certificate in DER format to PEM format, use OpenSSL
269       tools:
270
271           openssl x509 -inform DER -in cert.der -outform PEM > cert.pem
272
273       To sign some data stored in file data using the private key with ID ID
274       and using the RSA-PKCS mechanism:
275
276           pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sig
277
278

AUTHORS

280       pkcs11-tool was written by Olaf Kirch <okir@suse.de>.
281
282
283
284opensc                            09/30/2019                    PKCS11-TOOL(1)
Impressum