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 the public portion of the key as a PKCS
102 #15 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 the public portion of the key as a PKCS
113 #15 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
161 --version,
162 Print the OpenSC package release version.
163 --card-profile name, -c name
165 Tells pkcs15-init to load the specified card profile option. You
166 will rarely need this option.
167 --create-pkcs15, -C
169 This tells pkcs15-init to create a PKCS #15 structure on the card,
170 and initialize any PINs.
171 --erase-card, -E
173 This will erase the card prior to creating the PKCS #15 structure,
174 if the card supports it. If the card does not support erasing,
175 pkcs15-init will fail.
176 --generate-key keyspec, -G keyspec
178 Tells the card to generate new key and store it on the card.
179 keyspec consists of an algorithm name (currently, the only
180 supported name is RSA), optionally followed by a slash and the
181 length of the key in bits. It is a good idea to specify the key ID
182 along with this command, using the id option, otherwise an
183 intrinsic ID will be calculated from the key material. Look the
184 description of the 'pkcs15-id-style' attribut in the
185 'pkcs15.profile' for the details about the algorithm used to
186 calculate intrinsic ID. For the multi-application cards the target
187 PKCS#15 application can be specified by the hexadecimal AID value
188 of the aid option.
189 --options-file filename
191 Tells pkcs15-init to read additional options from filename. The
192 file is supposed to contain one long option per line, without the
193 leading dashes, for instance:
194 pin frank
196 puk zappa
197 You can specify --options-file several times.
199 --pin, --puk --so-pin, --so-puk,
201 These options can be used to specify PIN/PUK values on the command
202 line. If set to env:VARIABLE, the value of the environment variable
203 VARIABLE is used. Note that on most operation systems, any user can
204 display the command line of any process on the system using
205 utilities such as ps(1). Therefore, you should use these options
206 only on a secured system, or in an options file specified with
207 --options-file.
208 --profile name, -p name
210 Tells pkcs15-init to load the specified general profile. Currently,
211 the only application profile defined is pkcs15, but you can write
212 your own profiles and specify them using this option.
213 The profile name can be combined with one or more profile options,
215 which slightly modify the profile's behavior. For instance, the
216 default OpenSC profile supports the openpin option, which installs
217 a single PIN during card initialization. This PIN is then used both
218 as the SO PIN as well as the user PIN for all keys stored on the
219 card.
220 Profile name and options are separated by a + character, as in
222 pkcs15+onepin.
223 --store-certificate filename, -X filename
225 Tells pkcs15-init to store the certificate given in filename on the
226 card, creating a certificate object with the ID specified via the
227 --id option. Without supplied ID an intrisic ID will be calculated
228 from the certificate's public key. Look the description of the
229 'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
230 about the algorithm used to calculate intrinsic ID. The file is
231 assumed to contain the PEM encoded certificate. For the
232 multi-application cards the target application can be specified by
233 the hexadecimal AID value of the aid option.
234 --store-public-key filename
236 Tells pkcs15-init to download the specified public key to the card
237 and create a public key object with the key ID specified via the
238 --id. By default, the file is assumed to contain the key in PEM
239 format. Alternative formats can be specified using --format.
240 --store-private-key filename, -S filename
242 Tells pkcs15-init to download the specified private key to the
243 card. This command will also create a public key object containing
244 the public key portion. By default, the file is assumed to contain
245 the key in PEM format. Alternative formats can be specified using
246 --format. It is a good idea to specify the key ID along with this
247 command, using the --id option, otherwise an intrinsic ID will be
248 calculated from the key material. Look the description of the
249 'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
250 about the algorithm used to calculate intrinsic ID. For the
251 multi-application cards the target PKCS#15 application can be
252 specified by the hexadecimal AID value of the aid option.
253 --update-certificate filename, -U filename
255 Tells pkcs15-init to update the certificate object with the ID
256 specified via the --id option with the certificate in filename. The
257 file is assumed to contain a PEM encoded certificate.
258 Pay extra attention when updating mail decryption certificates, as
260 missing certificates can render e-mail messages unreadable!
261 --use-default-transport-keys, -T
263 Tells pkcs15-init to not ask for the transport keys and use default
264 keys, as known by the card driver.
265 --verbose, -v
267 Causes pkcs15-init to be more verbose. Specify this flag several
268 times to enable debug output in the OpenSC library.
269 --use-pinpad
271 Do not prompt the user; if no PINs supplied, pinpad will be used.
272
274 pkcs15-profile(5)
275openscopensc 10/30/2018 PKCS15-INITPKCS15-(1)