1PKCS15-INITPKCS15-(1)      OpenSC ToolsOpenSC Tools      PKCS15-INITPKCS15-(1)
2
3
4

NAME

6       pkcs15-init - smart card personalization utility
7

SYNOPSIS

9       pkcs15-init [OPTIONS]
10

DESCRIPTION

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
16       The profile used by default is pkcs15. Alternative profiles can be
17       specified via the -p switch.
18

PIN USAGE

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
24       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
30       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
35       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
44       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
48       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

MODES OF OPERATION

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
60       pkcs15-init --create-pkcs15
61
62       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
66       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
69   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
73       pkcs15-init --store-pin --id " nn
74
75       where nn is a PKCS #15 ID in hexadecimal notation. Common values are
76       01, 02, etc.
77
78       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
82       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
86   Key generation
87       pkcs15-init lets you generate a new key and store it on the card. You
88       can do this using:
89
90       pkcs15-init --generate-key " keyspec " --auth-id " nn
91
92       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
98       nn is the ID of a user PIN installed previously, e.g.  01.
99
100       In addition to storing the private portion of the key on the card,
101       pkcs15-init will also store the the public portion of the key as a PKCS
102       #15 public key object.
103
104   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
109       pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
110
111       In addition to storing the private portion of the key on the card,
112       pkcs15-init will also store the the public portion of the key as a PKCS
113       #15 public key object.
114
115       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
122       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
129   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
136       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
140   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
145   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
152       pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01
153
154       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
160   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
165       pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm
166       aes/256 --auth-id 01
167
168       By default a random ID is generated for the secret key. You may specify
169       an ID with the --id if needed.
170

OPTIONS

172       --version,
173           Print the OpenSC package release version.
174
175       --card-profile name, -c name
176           Tells pkcs15-init to load the specified card profile option. You
177           will rarely need this option.
178
179       --create-pkcs15, -C
180           This tells pkcs15-init to create a PKCS #15 structure on the card,
181           and initialize any PINs.
182
183       --serial SERIAL
184           Specify the serial number of the card.
185
186       --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
191       --erase-application AID
192           This will erase the application with the application identifier
193           AID.
194
195       --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
208       --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
213               pin       1234
214               puk       87654321
215
216
217           You can specify --options-file several times.
218
219       --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
228       --no-so-pin,
229           Do not install a SO PIN, and do not prompt for it.
230
231       --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
236           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
243           Profile name and options are separated by a + character, as in
244           pkcs15+onepin.
245
246       --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
250       --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
261       --store-pin, -P
262           Store a new PIN/PUK on the card.
263
264       --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
270       --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
283       --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
288           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
293       --store-data filename, -W filename
294           Store a data object.
295
296       --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
301           Pay extra attention when updating mail decryption certificates, as
302           missing certificates can render e-mail messages unreadable!
303
304       --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
309           When data is specified, an ---application-id must also be
310           specified, in the other cases an --id must also be specified
311
312           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
316       --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
322                                                       pkcs15-init -A cert --id 45 -a 1 --label Jim
323
324
325
326       --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
330       --sanity-check, -T
331           Tells pkcs15-init to perform a card specific sanity check and
332           possibly update procedure.
333
334       --reader num, -r num
335           Specify the reader to use. By default, the first reader with a
336           present card is used. If num is an ATR, the reader with a matching
337           card will be chosen.
338
339       --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
343       --wait, -w
344           Causes pkcs15-init to wait for a card insertion.
345
346       --use-pinpad
347           Do not prompt the user; if no PINs supplied, pinpad will be used.
348
349       --puk-id ID
350           Specify ID of PUK to use/create
351
352       --puk-label LABEL
353           Specify label of PUK
354
355       --public-key-label LABEL
356           Specify public key label (use with --generate-key)
357
358       --cert-label LABEL
359           Specify user cert label (use with --store-private-key)
360
361       --application-name arg
362           Specify application name of data object (use with
363           --store-data-object)
364
365       --aid AID
366           Specify AID of the on-card PKCS#15 application to be binded to (in
367           hexadecimal form)
368
369       --output-file filename -o filename,
370           Output public portion of generated key to file
371
372       --passphrase PASSPHRASE
373           Specify passphrase for unlocking secret key
374
375       --authority
376           Mark certificate as a CA certificate
377
378       --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
384           The alias sign is equivalent to
385           digitalSignature,keyCertSign,cRLSign
386
387           The alias decrypt is equivalent to keyEncipherment,dataEncipherment
388
389       --finalize -F,
390           Finish initialization phase of the smart card
391
392       --update-last-update
393           Update 'lastUpdate' attribute of tokenInfo
394
395       --ignore-ca-certificates
396           When storing PKCS#12 ignore CA certificates
397
398       --update-existing
399           Store or update existing certificate
400
401       --extractable
402           Private key stored as an extractable key
403
404       --insecure
405           Insecure mode: do not require a PIN for private key
406
407       --md-container-guid GUID
408           For a new key specify GUID for a MD container
409
410       --help -h,
411           Display help message
412

SEE ALSO

414       pkcs15-profile(5)
415

AUTHORS

417       pkcs15-init was written by Olaf Kirch <okir@suse.de>.
418
419
420
421openscopensc                      09/30/2019             PKCS15-INITPKCS15-(1)
Impressum