1PKCS15-INITPKCS15-(1) OpenSC ToolsOpenSC Tools PKCS15-INITPKCS15-(1)
2
6 pkcs15-init - smart card personalization utility
7
9 pkcs15-init [OPTIONS]
10
12 The pkcs15-init utility can be used to create a PKCS #15 structure on a
13 smart card, and add key or certificate objects. Details of the
14 structure that will be created are controlled via profiles.
15 The profile used by default is pkcs15. Alternative profiles can be
17 specified via the -p switch.
18
20 pkcs15-init can be used to create a PKCS #15 structure on your smart
21 card, create PINs, and install keys and certificates on the card. This
22 process is also called personalization.
23 An OpenSC card can have one security officer PIN, and zero or more user
25 PINs. PIN stands for Personal Identification Number, and is a secret
26 code you need to present to the card before being allowed to perform
27 certain operations, such as using one of the stored RSA keys to sign a
28 document, or modifying the card itself.
29 Usually, PINs are a sequence of decimal digits, but some cards will
31 accept arbitrary ASCII characters. Be aware however that using
32 characters other than digits will make the card unusable with PIN pad
33 readers, because those usually have keys for entering digits only.
34 The security officer (SO) PIN is special; it is used to protect meta
36 data information on the card, such as the PKCS #15 structure itself.
37 Setting the SO PIN is optional, because the worst that can usually
38 happen is that someone finding your card can mess it up. To extract any
39 of your secret keys stored on the card, an attacker will still need
40 your user PIN, at least for the default OpenSC profiles. However, it is
41 possible to create card profiles that will allow the security officer
42 to override user PINs.
43 For each PIN, you can specify a PUK (also called unblock PIN). The PUK
45 can be used to overwrite or unlock a PIN if too many incorrect values
46 have been entered in a row.
47 For some cards that use the PKCS#15 emulation, the attributes of
49 private objects are protected and cannot be parsed without
50 authentication (usually with User PIN). This authentication need to be
51 done immediately after the card binding. In such cases --verify-pin has
52 to be used.
53
55 Initialization
56 This is the first step during card personalization, and will create the
57 basic files on the card. To create the initial PKCS #15 structure,
58 invoke the utility as
59 pkcs15-init --create-pkcs15
61 You will then be asked for the security officer PIN and PUK. Simply
63 pressing return at the SO PIN prompt will skip installation of an SO
64 PIN.
65 If the card supports it, you should erase the contents of the card with
67 pkcs15-init --erase-card before creating the PKCS#15 structure.
68 User PIN Installation
70 Before installing any user objects such as private keys, you need at
71 least one PIN to protect these objects. you can do this using
72 pkcs15-init --store-pin --id " nn
74 where nn is a PKCS #15 ID in hexadecimal notation. Common values are
76 01, 02, etc.
77 Entering the command above will ask you for the user's PIN and PUK. If
79 you do not wish to install an unblock PIN, simply press return at the
80 PUK prompt.
81 To set a label for this PIN object (which can be used by applications
83 to display a meaningful prompt to the user), use the --label command
84 line option.
85 Key generation
87 pkcs15-init lets you generate a new key and store it on the card. You
88 can do this using:
89 pkcs15-init --generate-key " keyspec " --auth-id " nn
91 where keyspec describes the algorithm and length of the key to be
93 created, such as rsa/512. This will create a 512 bit RSA key.
94 Currently, only RSA key generation is supported. Note that cards
95 usually support just a few different key lengths. Almost all cards will
96 support 512 and 1024 bit keys, some will support 768 or 2048 as well.
97 nn is the ID of a user PIN installed previously, e.g. 01.
99 In addition to storing the private portion of the key on the card,
101 pkcs15-init will also store the public portion of the key as a PKCS #15
102 public key object.
103 Private Key Upload
105 You can use a private key generated by other means and upload it to the
106 card. For instance, to upload a private key contained in a file named
107 okir.pem, which is in PEM format, you would use
108 pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
110 In addition to storing the private portion of the key on the card,
112 pkcs15-init will also store the public portion of the key as a PKCS #15
113 public key object.
114 Note that usage of --id option in the pkcs15-init commands to generate
116 or to import a new key is deprecated. Better practice is to let the
117 middleware to derive the identifier from the key material.
118 (SHA1(modulus) for RSA, SHA1(pub) for DSA, ...). This allows easily set
119 up relation between 'related' objects (private/public keys and
120 certificates).
121 In addition to the PEM key file format, pkcs15-init also supports DER
123 encoded keys, and PKCS #12 files. The latter is the file format used by
124 Netscape Navigator (among others) when exporting certificates to a
125 file. A PKCS #12 file usually contains the X.509 certificate
126 corresponding to the private key. If that is the case, pkcs15-init will
127 store the certificate instead of the public key portion.
128 Public Key Upload
130 You can also upload individual public keys to the card using the
131 --store-public-key option, which takes a filename as an argument. This
132 file is supposed to contain the public key. If you don't specify a key
133 file format using the --format option, pkcs15-init will assume PEM
134 format. The only other supported public key file format is DER.
135 Since the corresponding public keys are always uploaded automatically
137 when generating a new key, or when uploading a private key, you will
138 probably use this option only very rarely.
139 Certificate Upload
141 You can upload certificates to the card using the --store-certificate
142 option, which takes a filename as an argument. This file is supposed to
143 contain the PEM encoded X.509 certificate.
144 Uploading PKCS #12 bags
146 Most browsers nowadays use PKCS #12 format files when you ask them to
147 export your key and certificate to a file. pkcs15-init is capable of
148 parsing these files, and storing their contents on the card in a single
149 operation. This works just like storing a private key, except that you
150 need to specify the file format:
151 pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01
153 This will install the private key contained in the file okir.p12, and
155 protect it with the PIN referenced by authentication ID 01. It will
156 also store any X.509 certificates contained in the file, which is
157 usually the user certificate that goes with the key, as well as the CA
158 certificate.
159 Secret Key Upload
161 You can use a secret key generated by other means and upload it to the
162 card. For instance, to upload an AES-secret key generated by the system
163 random generator you would use
164 pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm
166 aes/256 --auth-id 01
167 By default a random ID is generated for the secret key. You may specify
169 an ID with the --id if needed.
170
172 --version,
173 Print the OpenSC package release version.
174 --card-profile name, -c name
176 Tells pkcs15-init to load the specified card profile option. You
177 will rarely need this option.
178 --create-pkcs15, -C
180 This tells pkcs15-init to create a PKCS #15 structure on the card,
181 and initialize any PINs.
182 --serial SERIAL
184 Specify the serial number of the card.
185 --erase-card, -E
187 This will erase the card prior to creating the PKCS #15 structure,
188 if the card supports it. If the card does not support erasing,
189 pkcs15-init will fail.
190 --erase-application AID
192 This will erase the application with the application identifier
193 AID.
194 --generate-key keyspec, -G keyspec
196 Tells the card to generate new key and store it on the card.
197 keyspec consists of an algorithm name (currently, the only
198 supported name is RSA), optionally followed by a slash and the
199 length of the key in bits. It is a good idea to specify the key ID
200 along with this command, using the id option, otherwise an
201 intrinsic ID will be calculated from the key material. Look the
202 description of the 'pkcs15-id-style' attribute in the
203 'pkcs15.profile' for the details about the algorithm used to
204 calculate intrinsic ID. For the multi-application cards the target
205 PKCS#15 application can be specified by the hexadecimal AID value
206 of the aid option.
207 --options-file filename
209 Tells pkcs15-init to read additional options from filename. The
210 file is supposed to contain one long option per line, without the
211 leading dashes, for instance:
212 pin 1234
214 puk 87654321
215 You can specify --options-file several times.
218 --pin, --puk --so-pin, --so-puk,
220 These options can be used to specify PIN/PUK values on the command
221 line. If set to env:VARIABLE, the value of the environment variable
222 VARIABLE is used. Note that on most operation systems, any user can
223 display the command line of any process on the system using
224 utilities such as ps(1). Therefore, you should use these options
225 only on a secured system, or in an options file specified with
226 --options-file.
227 --no-so-pin,
229 Do not install a SO PIN, and do not prompt for it.
230 --profile name, -p name
232 Tells pkcs15-init to load the specified general profile. Currently,
233 the only application profile defined is pkcs15, but you can write
234 your own profiles and specify them using this option.
235 The profile name can be combined with one or more profile options,
237 which slightly modify the profile's behavior. For instance, the
238 default OpenSC profile supports the openpin option, which installs
239 a single PIN during card initialization. This PIN is then used both
240 as the SO PIN as well as the user PIN for all keys stored on the
241 card.
242 Profile name and options are separated by a + character, as in
244 pkcs15+onepin.
245 --secret-key-algorithm keyspec,
247 keyspec describes the algorithm and length of the key to be created
248 or downloaded, such as aes/256. This will create a 256 bit AES key.
249 --store-certificate filename, -X filename
251 Tells pkcs15-init to store the certificate given in filename on the
252 card, creating a certificate object with the ID specified via the
253 --id option. Without supplied ID an intrinsic ID will be calculated
254 from the certificate's public key. Look the description of the
255 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
256 about the algorithm used to calculate intrinsic ID. The file is
257 assumed to contain the PEM encoded certificate. For the
258 multi-application cards the target application can be specified by
259 the hexadecimal AID value of the aid option.
260 --store-pin, -P
262 Store a new PIN/PUK on the card.
263 --store-public-key filename
265 Tells pkcs15-init to download the specified public key to the card
266 and create a public key object with the key ID specified via the
267 --id. By default, the file is assumed to contain the key in PEM
268 format. Alternative formats can be specified using --format.
269 --store-private-key filename, -S filename
271 Tells pkcs15-init to download the specified private key to the
272 card. This command will also create a public key object containing
273 the public key portion. By default, the file is assumed to contain
274 the key in PEM format. Alternative formats can be specified using
275 --format. It is a good idea to specify the key ID along with this
276 command, using the --id option, otherwise an intrinsic ID will be
277 calculated from the key material. Look the description of the
278 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
279 about the algorithm used to calculate intrinsic ID. For the
280 multi-application cards the target PKCS#15 application can be
281 specified by the hexadecimal AID value of the aid option.
282 --store-secret-key filename,
284 Tells pkcs15-init to download the specified secret key to the card.
285 The file is assumed to contain the raw key. They key type should be
286 specified with --secret-key-algorithm option.
287 You may additionally specify the key ID along with this command,
289 using the --id option, otherwise a random ID is generated. For the
290 multi-application cards the target PKCS#15 application can be
291 specified by the hexadecimal AID value of the aid option.
292 --store-data filename, -W filename
294 Store a data object.
295 --update-certificate filename, -U filename
297 Tells pkcs15-init to update the certificate object with the ID
298 specified via the --id option with the certificate in filename. The
299 file is assumed to contain a PEM encoded certificate.
300 Pay extra attention when updating mail decryption certificates, as
302 missing certificates can render e-mail messages unreadable!
303 --delete-objects arg, -D arg
305 Tells pkcs15-init to delete the specified object. arg is
306 comma-separated list containing any of privkey, pubkey, secrkey,
307 cert, chain or data.
308 When data is specified, an ---application-id must also be
310 specified, in the other cases an --id must also be specified
311 When chain is specified, the certificate chain starting with the
313 cert with specified ID will be deleted, until there's a CA
314 certificate that certifies another cert on the card
315 --change-attributes arg, -A arg
317 Tells pkcs15-init to change the specified attribute. arg is either
318 privkey, pubkey, secrkey, cert or data. You also have to specify
319 the --id of the object. For now, you can only change the --label,
320 e.g:
321 pkcs15-init -A cert --id 45 -a 1 --label Jim
323 --use-default-transport-keys, -T
327 Tells pkcs15-init to not ask for the transport keys and use default
328 keys, as known by the card driver.
329 --sanity-check, -T
331 Tells pkcs15-init to perform a card specific sanity check and
332 possibly update procedure.
333 --reader arg, -r arg
335 Number of the reader to use. By default, the first reader with a
336 present card is used. If arg is an ATR, the reader with a matching
337 card will be chosen.
338 --verbose, -v
340 Causes pkcs15-init to be more verbose. Specify this flag several
341 times to enable debug output in the OpenSC library.
342 --wait, -w
344 Causes pkcs15-init to wait for a card insertion.
345 --use-pinpad
347 Do not prompt the user; if no PINs supplied, pinpad will be used.
348 --puk-id ID
350 Specify ID of PUK to use/create
351 --puk-label LABEL
353 Specify label of PUK
354 --public-key-label LABEL
356 Specify public key label (use with --generate-key)
357 --cert-label LABEL
359 Specify user cert label (use with --store-private-key)
360 --application-name arg
362 Specify application name of data object (use with
363 --store-data-object)
364 --aid AID
366 Specify AID of the on-card PKCS#15 application to be binded to (in
367 hexadecimal form)
368 --output-file filename -o filename,
370 Output public portion of generated key to file
371 --passphrase PASSPHRASE
373 Specify passphrase for unlocking secret key
374 --authority
376 Mark certificate as a CA certificate
377 --key-usage arg -u arg,
379 Specifies the X.509 key usage. arg is comma-separated list
380 containing any of digitalSignature, nonRepudiation,
381 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign,
382 cRLSign. Abbreviated names are allowed if unique (e.g. dataEnc).
383 The alias sign is equivalent to
385 digitalSignature,keyCertSign,cRLSign
386 The alias decrypt is equivalent to keyEncipherment,dataEncipherment
388 --finalize -F,
390 Finish initialization phase of the smart card
391 --update-last-update
393 Update 'lastUpdate' attribute of tokenInfo
394 --ignore-ca-certificates
396 When storing PKCS#12 ignore CA certificates
397 --update-existing
399 Store or update existing certificate
400 --extractable
402 Private key stored as an extractable key
403 --user-consent arg
405 Specify user-consent. arg is an integer value. If > 0, the value
406 specifies how many times the object can be accessed before a new
407 authentication is required. If zero, the object does not require
408 re-authentication.
409 --insecure
411 Insecure mode: do not require a PIN for private key
412 --md-container-guid GUID
414 For a new key specify GUID for a MD container
415 --help -h,
417 Display help message
418
420 pkcs15-profile(5)
421
423 pkcs15-init was written by Olaf Kirch <okir@suse.de>.
424openscopensc 02/10/2020 PKCS15-INITPKCS15-(1)