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 the parameters of the key to
93       be created. For example, rsa:2048 generates a RSA key with 2048-bit
94       modulus. If you are generating an EC key, the curve designation must be
95       specified, for example ec:prime256v1. For symmetric key, the length of
96       key is specified in bytes, for example AES:32 or DES3:24.
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 public portion of the key as a PKCS #15
102       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 public portion of the key as a PKCS #15
113       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, ...). This allows easily set up relation
119       between 'related' objects (private/public keys and certificates).
120
121       In addition to the PEM key file format, pkcs15-init also supports DER
122       encoded keys, and PKCS #12 files. The latter is the file format used by
123       Netscape Navigator (among others) when exporting certificates to a
124       file. A PKCS #12 file usually contains the X.509 certificate
125       corresponding to the private key. If that is the case, pkcs15-init will
126       store the certificate instead of the public key portion.
127
128   Public Key Upload
129       You can also upload individual public keys to the card using the
130       --store-public-key option, which takes a filename as an argument. This
131       file is supposed to contain the public key. If you don't specify a key
132       file format using the --format option, pkcs15-init will assume PEM
133       format. The only other supported public key file format is DER.
134
135       Since the corresponding public keys are always uploaded automatically
136       when generating a new key, or when uploading a private key, you will
137       probably use this option only very rarely.
138
139   Certificate Upload
140       You can upload certificates to the card using the --store-certificate
141       option, which takes a filename as an argument. This file is supposed to
142       contain the PEM encoded X.509 certificate.
143
144   Uploading PKCS #12 bags
145       Most browsers nowadays use PKCS #12 format files when you ask them to
146       export your key and certificate to a file.  pkcs15-init is capable of
147       parsing these files, and storing their contents on the card in a single
148       operation. This works just like storing a private key, except that you
149       need to specify the file format:
150
151       pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01
152
153       This will install the private key contained in the file okir.p12, and
154       protect it with the PIN referenced by authentication ID 01. It will
155       also store any X.509 certificates contained in the file, which is
156       usually the user certificate that goes with the key, as well as the CA
157       certificate.
158
159   Secret Key Upload
160       You can use a secret key generated by other means and upload it to the
161       card. For instance, to upload an AES-secret key generated by the system
162       random generator you would use
163
164       pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm
165       aes:256 --auth-id 01
166
167       By default a random ID is generated for the secret key. You may specify
168       an ID with the --id if needed.
169

OPTIONS

171       --version,
172           Print the OpenSC package release version.
173
174       --card-profile name, -c name
175           Tells pkcs15-init to load the specified card profile option. You
176           will rarely need this option.
177
178       --create-pkcs15, -C
179           This tells pkcs15-init to create a PKCS #15 structure on the card,
180           and initialize any PINs.
181
182       --serial SERIAL
183           Specify the serial number of the card.
184
185       --erase-card, -E
186           This will erase the card prior to creating the PKCS #15 structure,
187           if the card supports it. If the card does not support erasing,
188           pkcs15-init will fail.
189
190       --erase-application AID
191           This will erase the application with the application identifier
192           AID.
193
194       --generate-key keyspec, -G keyspec
195           Tells the card to generate new key and store it on the card.
196           keyspec consists of an algorithm name, optionally followed by a
197           colon ":", slash "/" or hyphen "-" and the parameters of the key to
198           be created. It is a good idea to specify the key ID along with this
199           command, using the id option, otherwise an intrinsic ID will be
200           calculated from the key material. Look the description of the
201           'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
202           about the algorithm used to calculate intrinsic ID. For the
203           multi-application cards the target PKCS#15 application can be
204           specified by the hexadecimal AID value of the aid option.
205
206       --pin pin, --puk puk, --so-pin sopin, --so-puk sopuk
207           These options can be used to specify the PIN/PUK values on the
208           command line. If the value is set to env:VARIABLE, the value of the
209           specified environment variable is used. By default, the code is
210           prompted on the command line if needed.
211
212           Note that on most operation systems, any user can display the
213           command line of any process on the system using utilities such as
214           ps(1). Therefore, you should prefer passing the codes via an
215           environment variable on an unsecured system.
216
217       --no-so-pin,
218           Do not install a SO PIN, and do not prompt for it.
219
220       --profile name, -p name
221           Tells pkcs15-init to load the specified general profile. Currently,
222           the only application profile defined is pkcs15, but you can write
223           your own profiles and specify them using this option.
224
225           The profile name can be combined with one or more profile options,
226           which slightly modify the profile's behavior. For instance, the
227           default OpenSC profile supports the openpin option, which installs
228           a single PIN during card initialization. This PIN is then used both
229           as the SO PIN as well as the user PIN for all keys stored on the
230           card.
231
232           Profile name and options are separated by a + character, as in
233           pkcs15+onepin.
234
235       --secret-key-algorithm keyspec,
236           keyspec describes the algorithm and length of the key to be created
237           or downloaded, such as aes:256. This will create a 256 bit AES key.
238
239       --store-certificate filename, -X filename
240           Tells pkcs15-init to store the certificate given in filename on the
241           card, creating a certificate object with the ID specified via the
242           --id option. Without supplied ID an intrinsic ID will be calculated
243           from the certificate's public key. Look the description of the
244           'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
245           about the algorithm used to calculate intrinsic ID. The file is
246           assumed to contain the PEM encoded certificate. For the
247           multi-application cards the target application can be specified by
248           the hexadecimal AID value of the aid option.
249
250       --store-pin, -P
251           Store a new PIN/PUK on the card.
252
253       --store-public-key filename
254           Tells pkcs15-init to download the specified public key to the card
255           and create a public key object with the key ID specified via the
256           --id. By default, the file is assumed to contain the key in PEM
257           format. Alternative formats can be specified using --format.
258
259       --store-private-key filename, -S filename
260           Tells pkcs15-init to download the specified private key to the
261           card. This command will also create a public key object containing
262           the public key portion. By default, the file is assumed to contain
263           the key in PEM format. Alternative formats can be specified using
264           --format. It is a good idea to specify the key ID along with this
265           command, using the --id option, otherwise an intrinsic ID will be
266           calculated from the key material. Look the description of the
267           'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
268           about the algorithm used to calculate intrinsic ID. For the
269           multi-application cards the target PKCS#15 application can be
270           specified by the hexadecimal AID value of the aid option.
271
272       --store-secret-key filename,
273           Tells pkcs15-init to download the specified secret key to the card.
274           The file is assumed to contain the raw key. They key type should be
275           specified with --secret-key-algorithm option.
276
277           You may additionally specify the key ID along with this command,
278           using the --id option, otherwise a random ID is generated. For the
279           multi-application cards the target PKCS#15 application can be
280           specified by the hexadecimal AID value of the aid option.
281
282       --store-data filename, -W filename
283           Store a data object.
284
285       --update-certificate filename, -U filename
286           Tells pkcs15-init to update the certificate object with the ID
287           specified via the --id option with the certificate in filename. The
288           file is assumed to contain a PEM encoded certificate.
289
290           Pay extra attention when updating mail decryption certificates, as
291           missing certificates can render e-mail messages unreadable!
292
293       --delete-objects arg, -D arg
294           Tells pkcs15-init to delete the specified object.  arg is
295           comma-separated list containing any of privkey, pubkey, secrkey,
296           cert, chain or data.
297
298           When data is specified, an ---application-id must also be
299           specified, in the other cases an --id must also be specified
300
301           When chain is specified, the certificate chain starting with the
302           cert with specified ID will be deleted, until there's a CA
303           certificate that certifies another cert on the card
304
305       --change-attributes arg, -A arg
306           Tells pkcs15-init to change the specified attribute.  arg is either
307           privkey, pubkey, secrkey, cert or data. You also have to specify
308           the --id of the object. For now, you can only change the --label,
309           e.g:
310
311                                                       pkcs15-init -A cert --id 45 -a 1 --label Jim
312
313
314
315       --use-default-transport-keys, -T
316           Tells pkcs15-init to not ask for the transport keys and use default
317           keys, as known by the card driver.
318
319       --sanity-check, -T
320           Tells pkcs15-init to perform a card specific sanity check and
321           possibly update procedure.
322
323       --reader arg, -r arg
324           Number of the reader to use. By default, the first reader with a
325           present card is used. If arg is an ATR, the reader with a matching
326           card will be chosen.
327
328       --verbose, -v
329           Causes pkcs15-init to be more verbose. Specify this flag several
330           times to enable debug output in the OpenSC library.
331
332       --wait, -w
333           Causes pkcs15-init to wait for a card insertion.
334
335       --use-pinpad
336           Do not prompt the user; if no PINs supplied, pinpad will be used.
337
338       --puk-id ID
339           Specify ID of PUK to use/create
340
341       --label LABEL
342           Specify label for a PIN, key, certificate or data object when
343           creating a new objects. When deleting objects, this can be used to
344           delete object by label.
345
346       --puk-label LABEL
347           Specify label of PUK
348
349       --public-key-label LABEL
350           Specify public key label (use with --generate-key)
351
352       --cert-label LABEL
353           Specify user cert label (use with --store-private-key)
354
355       --application-name arg
356           Specify application name of data object (use with
357           --store-data-object)
358
359       --aid AID
360           Specify AID of the on-card PKCS#15 application to be binded to (in
361           hexadecimal form)
362
363       --output-file filename -o filename,
364           Output public portion of generated key to file
365
366       --passphrase PASSPHRASE
367           Specify passphrase for unlocking secret key
368
369       --authority
370           Mark certificate as a CA certificate
371
372       --key-usage arg -u arg,
373           Specifies the X.509 key usage.  arg is comma-separated list
374           containing any of digitalSignature, nonRepudiation,
375           keyEncipherment, dataEncipherment, keyAgreement, keyCertSign,
376           cRLSign. Abbreviated names are allowed if unique (e.g.  dataEnc).
377
378           The alias sign is equivalent to
379           digitalSignature,keyCertSign,cRLSign
380
381           The alias decrypt is equivalent to keyEncipherment,dataEncipherment
382
383       --finalize -F,
384           Finish initialization phase of the smart card
385
386       --update-last-update
387           Update 'lastUpdate' attribute of tokenInfo
388
389       --ignore-ca-certificates
390           When storing PKCS#12 ignore CA certificates
391
392       --update-existing
393           Store or update existing certificate
394
395       --extractable
396           Private key stored as an extractable key
397
398       --user-consent arg
399           Specify user-consent.  arg is an integer value. If > 0, the value
400           specifies how many times the object can be accessed before a new
401           authentication is required. If zero, the object does not require
402           re-authentication.
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                      08/08/2023             PKCS15-INITPKCS15-(1)
Impressum