1PKCS15-INIT(1) OpenSC tools PKCS15-INIT(1)
2
6 pkcs15-init - smart card personalization utility
7
9 The pkcs15-init utility can be used to create a PKCS #15 structure on a
10 smart card, and add key or certificate objects. Details of the
11 structure that will be created are controlled via profiles.
12 The profile used by default is pkcs15. Alternative profiles can be
14 specified via the -p switch.
15
17 pkcs15-init can be used to create a PKCS #15 structure on your smart
18 card, create PINs, and install keys and certificates on the card. This
19 process is also called personalization.
20 An OpenSC card can have one security officer PIN, and zero or more user
22 PINs. PIN stands for Personal Identification Number, and is a secret
23 code you need to present to the card before being allowed to perform
24 certain operations, such as using one of the stored RSA keys to sign a
25 document, or modifying the card itself.
26 Usually, PINs are a sequence of decimal digits, but some cards will
28 accept arbitrary ASCII characters. Be aware however that using
29 characters other than digits will make the card unusable with PIN pad
30 readers, because those usually have keys for entering digits only.
31 The security officer (SO) PIN is special; it is used to protect meta
33 data information on the card, such as the PKCS #15 structure itself.
34 Setting the SO PIN is optional, because the worst that can usually
35 happen is that someone finding your card can mess it up. To extract any
36 of your secret keys stored on the card, an attacker will still need
37 your user PIN, at least for the default OpenSC profiles. However, it is
38 possible to create card profiles that will allow the security officer
39 to override user PINs.
40 For each PIN, you can specify a PUK (also called unblock PIN). The PUK
42 can be used to overwrite or unlock a PIN if too many incorrect values
43 have been entered in a row.
44
46 Initialization
47 This is the first step during card personalization, and will create the
48 basic files on the card. To create the initial PKCS #15 structure,
49 invoke the utility as
50 pkcs15-init --create-pkcs15
52 You will then be asked for several the security officer PIN and PUK.
54 Simply pressing return at the SO PIN prompt will skip installation of
55 an SO PIN.
56 If the card supports it, you can also request that the card is erased
58 prior to creating the PKCS #15 structure, by specifying the
59 --erase-card option.
60 User PIN Installation
62 Before installing any user objects such as private keys, you need at
63 least one PIN to protect these objects. you can do this using
64 pkcs15-init --store-pin --id " nn
66 where nn is a PKCS #15 ID in hexadecimal notation. Common values are
68 01, 02, etc.
69 Entering the command above will ask you for the user's PIN and PUK. If
71 you do not wish to install an unblock PIN, simply press return at the
72 PUK prompt.
73 To set a label for this PIN object (which can be used by applications
75 to display a meaningful prompt to the user), use the --label command
76 line option.
77 Key generation
79 pkcs15-init lets you generate a new key and store it on the card. You
80 can do this using:
81 pkcs15-init --generate-key " keyspec " --auth-id " nn
83 where keyspec describes the algorithm and length of the key to be
85 created, such as rsa/512. This will create a 512 bit RSA key.
86 Currently, only RSA key generation is supported. Note that cards
87 usually support just a few different key lengths. Almost all cards will
88 support 512 and 1024 bit keys, some will support 768 or 2048 as well.
89 nn is the ID of a user PIN installed previously, e.g. 01.
91 In addition to storing the private portion of the key on the card,
93 pkcs15-init will also store the the public portion of the key as a PKCS
94 #15 public key object.
95 By default, pkcs15-init will try to use the card's on-board key
97 generation facilities, if available. If the card does not support
98 on-board key generation, pkcs15-init will fall back to software key
99 generation.
100 Private Key Download
102 You can use a private key generated by other means and download it to
103 the card. For instance, to download a private key contained in a file
104 named okir.pem, which is in PEM format, you would use
105 pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
107 If the key is protected by a pass phrase, pkcs15-init will prompt you
109 for a pass phrase to unlock the key.
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 the use of the --id option. The current pkcs15 profile defines two
116 key templates, one for authentication (key ID 45), and one for
117 non-repudiation purposes (key ID 46). Other key templates will probably
118 be added in the future. Note that if you don't specify a key ID,
119 pkcs15-init will pick just the first key template defined by the
120 profile.
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 Download
130 You can also download 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 downloaded automatically
137 when generating a new key, or when downloading a private key, you will
138 probably use this option only very rarely.
139 Certificate Download
141 You can download 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 DER encoded X.509 certificate.
144 Downloading 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 --profile name, -p name
162 Tells pkcs15-init to load the specified general profile. Currently,
163 the only application profile defined is pkcs15, but you can write
164 your own profiles and specify them using this option.
165 The profile name can be combined with one or more profile options,
167 which slightly modify the profile's behavior. For instance, the
168 default OpenSC profile supports the openpin option, which installs a
169 single PIN during card initialization. This PIN is then used both as
170 the SO PIN as well as the user PIN for all keys stored on the card.
171 Profile name and options are separated by a + character, as in
173 pkcs15+onepin.
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 --erase-card, -E
184 This will erase the card prior to creating the PKCS #15 structure,
185 if the card supports it. If the card does not support erasing,
186 pkcs15-init will fail.
187 --generate-key keyspec, -G keyspec
189 Tells the card to generate new key and store it on the card.
190 keyspec consists of an algorithm name (currently, the only supported
191 name is RSA), optionally followed by a slash and the length of the
192 key in bits. It is a good idea to specify the key ID along with this
193 command, using the id option.
194 --store-private-key filename, -S filename
196 Tells pkcs15-init to download the specified private key to the card.
197 This command will also create a public key object containing the
198 public key portion. By default, the file is assumed to contain the
199 key in PEM format. Alternative formats can be specified using
200 --format. It is a good idea to specify the key ID along with this
201 command, using the --id option.
202 --store-public-key filename, -P filename
204 Tells pkcs15-init to download the specified public key to the card
205 and create a public key object with the key ID specified via the
206 --id. By default, the file is assumed to contain the key in PEM
207 format. Alternative formats can be specified using --format.
208 --store-certificate filename, -X filename
210 Tells pkcs15-init to store the certificate given in filename on the
211 card, creating a certificate object with the ID specified via the
212 --id option. The file is assumed to contain the DER encoded
213 certificate.
214 --so-pin, --so-puk, --pin, --puk
216 These options can be used to specify PIN/PUK values on the command
217 line. Note that on most operation systems, any user can display the
218 command line of any process on the system using utilities such as
219 ps(1). Therefore, you should use these options only on a secured
220 system, or in an options file specified with --options-file.
221 --passphrase
223 When downloading a private key, this option can be used to specify
224 the pass phrase to unlock the private key. The same caveat applies
225 here as in the case of the --pin options.
226 --options-file filename
228 Tells pkcs15-init to read additional options from filename. The file
229 is supposed to contain one long option per line, without the leading
230 dashes, for instance:
231 pin frank
233 puk zappa
234 You can specify --options-file several times.
237 --verbose, -v
239 Causes pkcs15-init to be more verbose. Specify this flag several
240 times to enable debug output in the OpenSC library.
241
243 pkcs15-profile(5)
244opensc 05/04/2007 PKCS15-INIT(1)