/
Pkcs15Init.html
448 lines (445 loc) · 22.2 KB
/
Pkcs15Init.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:html="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Pkcs15Init - OpenSC - Trac</title><style type="text/css">
@import url(trac.css);
</style></head><body><div class="wikipage">
<div id="searchable"><h1>1. Introduction</h1>
<blockquote>
<blockquote>
<blockquote>
<p>
Nothing is impossible for the man who doesn't
have to do it himself. -- A.H. Weiler
</p>
</blockquote>
</blockquote>
</blockquote>
<p>
This guide is about initialising and personalising (no distinction made) cards
with the OpenSC library and tools (mostly pkcs15-init).
</p>
<p>
Some knowlegde about smart cards is assumed. Below is a short overview of some
key words and concepts. For more info, see the opensc.html manual.
</p>
<p>
Filesystem - MF - DF - EF - FID<br></br>
A smart cards has a non-volatile memory (EEPROM) in which usually a
PC-like file system is implemented. The directories are called Dedicated Files
(DF) and the files are called Elementary Files (EF). They are identified by a
a File ID (FID) on 2 bytes. For example, the root of the file system (called
Master File or MF) has FID = 3F 00 (hex).
</p>
<p>
Commands - APDUs<br></br>
It is possible to send commands (APDUs) to the card to select, read, write,
create, list, delete, ... EFs and DFs (not all cards allow all commands).
</p>
<p>
Access control, PIN, PUK<br></br>
The file system usually implements some sort of access control on EFs and DFs.
This is usually done by PINs or Keys: you have to provide a PIN or show
knowledge of a key before you can perform some command on some EF/DF. A PIN
is usually accompanied by a PUK (Pin Unblock Key), which can be used to reset
(or unblock) that PIN.
</p>
<p>
Cryptographic keys<br></br>
On crypto cards, it is also possible to sign, decrypt, generate a key pair
(what can be done exactly depends on the card). on some cards, key and/or PINs
are files in the filesystem, on other cards, they don't exist in the
filesystem but are referenced through an ID.
</p>
<p>
Reader - PC/SC - OpenCT - CT-API<br></br>
Smart card readers come with a library that can be used on a PC to send APDUs
to the card. Commonly used APIs for those libraries are PC/SC, OpenCT and
CT-API.
</p>
<p>
PKCS#15<br></br>
There are standards (e.g. ISO7816, parts 4-...) that specify how to select,
read, write, EFs and DFs, and how to sign, decrypt, login, ...
However, there is also a need to know which files contain what, or where the
keys, PINs, .. can be found.
</p>
<p>
For crypto cards, PKCS15 adresses this need by defining some files that contain
info on where to find keys, certificates, PINs, and other data. For example,
there is a PrKDF (Private Key Directory File) that contains the EFs or ID of
the private keys, what those keys can be used for, by which PINs they are
protected, ...
</p>
<p>
So a "PCKS#5 card" is nothing but any other card on which the right set of
files has been added.
In short: PKCS15 allows you to describe where to find PINs, keys, certificates
and data on a card, plus all the info that is needed to use them.
</p>
<h2>A little PKCS!#15 example</h2>
<p>
Here's the textual contents of 3 PKCS#15 files: the AODF (Authentication
Object Directory File), PrKDF (Private Key Directory File) and CDF
(Certificate Directory File) that contain info on resp. the PINs, private
keys and certificates. Each of them contains 1 entry.
</p>
<pre class="wiki" xml:space="preserve">AODF:
Com. Flags : private, modifiable
Auth ID : 01
Flags : [0x32], local, initialized, needs-padding
Length : min_len:4, max_len:8, stored_len:8
Pad char : 0x00
Reference : 1
Encoding : ASCII-numeric
Path : 3F005015
PrKDF:
Com. Flags : private, modifiable
Com. Auth ID: 01
Usage : [0x32E], decrypt, sign, signRecover, unwrap, derive, nonRep
Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
ModLength : 1024
Key ref : 0
Native : yes
Path : 3F00501530450012
ID : 45
X.509 Certificate [/C=BE/ST=...]
Com. Flags : modifiable
Authority : no
Path : 3f0050154545
ID : 45
</pre><p>
Some things to note:
</p>
<ul><li>The Auth ID (01) of the private key is the same as the one of the PIN which
means that you first have to do a login with this PIN before you can use
this key.
</li><li>The key is in an EF with ID = 0012 in the DF with ID = 3045, which on its
turn is a DF with ID = 5015, which on its turn is a DF of the MF (3F00).
</li><li>The private key and certificate share the same ID (45), which means that they
belong together.
</li><li>The cert is in the EF with as path: 3F00\5015\4545 and is no CA cert.
</li></ul><p>
Use the <tt>pkcs15-tool --dump</tt> tool to see yourself what pkcs15 data is on
your card, or <tt>opensc-explorer</tt> to browse through the files.
</p>
<p>
Have the PKCS#15 files a fixed place so everyone can find them? No, there's
only one: the EF(DIR) in the MF and with ID 2F00. That's the starting place.
</p>
<h1>2. The OpenSC pkcs15-init library and profiles</h1>
<p>
Reading and writing files, PIN verification, signing and decryption happen in
much the same way on all cards. Therefore, the "normal life" commands have
been implemented in OpenSC for all supported cards.
</p>
<p>
However, creating and deleting files, PINs and keys is very card specific and
has not yet been implemented for all cards. Currently, pkcs15-init is
implemented for: Cryptoflex, Cyberflex, CardOS (etoken), GPK, Miocos, Starcos
JCOP and Oberthur. (Check src/pkcs15init/pkcs15-*.c for possible updates).
Because of this, and because pkcs15-init is not necessary for "normal life"
operations, it has been put in a separate library and in a separate directory.
</p>
<p>
Profile<br></br>
Because the initialisation/personalisation is so card-specific, it would be
very hard to make a tool or API that accepts all parameters for all current
and future cards. Therefore, a profile file has been made in OpenSC that
contains all the card-specific parameters. This card-specific profile is read
by card-specific code in the pkcs15-init library each time this library is
used on that card.
See the *.profile files in src/pkcs15init/. There is one general file
(pkcs15.profile) and one card-specific profile for each card.
</p>
<p>
Profile options <br></br>
There are currently 3 options you can specify to modify a profile:
</p>
<ul><li>default: creation/deletion/generation is controlled by the SO PIN (SO =
Security Officer, different from the regular user of the card)
</li><li>onepin: creation/deletion/generation is controlled by the user PIN and thus
by the user. As a result, only 1 user PIN is possible
</li><li>small: like default, but suitable for card with little memory
</li></ul><h1>3. pkcs15-init tool</h1>
<p>
This is a command-line tool that uses the pkcs15-init library. It allows you
to do all the init/perso things, e.g. add/delete keys, certificates, PINs and
data, generate keys, ... while specifying key usage, which PIN protects
which key, ...
</p>
<p>
As said before, not all cards are supported in the pkcs15-init library. In that
case, the pkcs15-init tool won't work (top 5 questions on the mailing list :-).
To find out which card you have, try "opensc-tool -n"
</p>
<p>
Below is explained how to do the operations that are supported by pkcs15-tool.
Not all options are explained (run "pkcs15-tool -h" to see them) because some
are card-specific or obsolete (or we don't know about them). Feel free to
experiment and explain them here.
</p>
<p>
So the things in this section are fairly general but not guaranteed to work
for all cards. See also the section on "card-specific issues".
</p>
<p>
The --reader or -r can be given with any command. By default the first reader
is used. Do "opensc-tool -l" to see the list of available readers.
</p>
<p>
The typical order of the commands is:
</p>
<ul><li>erase (-E) the card if needed
</li><li>create (-C) the PKCS15 files
</li><li>add a user PIN (unless you did a '-C' with the 'onepin' profile option)
</li><li>add a key + cert (-S) or generate a key (-G) + a add a cert (-W)
</li></ul><p>
To see the results of what you did, you can do one of the following:
</p>
<pre class="wiki" xml:space="preserve"> pkcs15-tool --list-pins --list-public-keys -k -c -C
pkcs15-tool --dump
</pre><p>
To see/dump the content of any file, use the opensc-explorer tool.
</p>
<h2>Create the PKCS15 files</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -C {-T} {-p <profile>}
--so-pin <PIN> --so-puk <PUK> | --no-so-pin | --pin <PIN> --puk <PUK>
</pre><p>
This will create the PKCS15 DF (5015) and all the PKCS15 files (some of which
will be empty until a key, PIN, ... will be added). It must be done before you
can do any of the operations below.
</p>
<ul><li>This operation usually requires a 'transport' key. pkcs15-init will ask you
for this key and propose the default one for that card. With -T, the default
key will be used without asking. NOTE: if you get a "Failed to erase card:
PIN code or key incorrect", the transport key is wrong. Find this key and
then try again, DO NOT try with the default key again!
</li><li>If you want an SO PIN and PUK, do so with the --so-pin and --so-puk options,
or specify --no-so-pin if you don't want them. If you use the onepin profile,
there is no SO PIN so you should specify --pin and --puk instead.
(So you get: pkcs15-init -CT -p pkcs15+onepin --pin <PIN> --puk <PUK>)
</li><li>To specify the profile file + option. The profile file can only be "pkcs15"
for the moment, so you can have:
<pre class="wiki" xml:space="preserve"> pkcs15+default : the default (not needed to specify it)
pkcs15+onepin : for the onepin profile option
pkcs15+small : for the small profile option
</pre></li></ul><h2>Erase the card's content</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -E {-T}
</pre><p>
This will delete all keys, PINs, certificates, data that were listed in PKCS15
files, along with the PKCS15 files themselves.
</p>
<ul><li>This operation usually requires a 'transport' key. pkcs15-init will ask you
for this key and propose the default one for that card. With -T, the default
key will be used without asking. NOTE: if you get a "Failed to erase card:
PIN code or key incorrect", the transport key is wrong. Find this key and
then try again, DO NOT try the default key again!
</li></ul><p>
Note: you can combine erase/create (-E -C or -EC) to erase and then create
the card's contents, except when you change the profile option.
</p>
<h2>Add a PIN (not possible with the onepin profile option)</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -P {-a <AuthID>} {--pin <PIN>} {--puk <PUK>} {-l <label>}
</pre><ul><li>You can specify the AuthID with -a, if you don't do so, a value that didn't
exist yet on the card will be used.
</li><li>Specify the PIN and PUK with --pin and --puk, if you don't do so, the tool
will prompt you for one.
</li><li>Specify the label (name) of the PIN with -l, or accept the default label.
</li></ul><h2>Generate a key pair (on card or in software on the PC)</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -G <keyspec> -a <AuthID> --insecure {-i <ID>} {--soft}
{-u <keyusage>}
{-l <privkeylabel>} {--public-key-label <pubkeylabel>}
</pre><p>
This will generate a public and private key pair.
</p>
<ul><li>The keyspec consist of the key type, rsa or dsa (depends on what your card
supports), and optinally a slash followed by the keysize in bits. E.g.
"rsa/1024" specifies a 1024-bit RSA key pair. Note: dsa is not fully
supported.
</li><li>Specify the AuthID of the PIN that protects this key (protect from being
used in a signature or decryption operation) with -a; or specify --insecure
if you want the private key to be used without first providing a PIN.
</li><li>Specify the ID of the key with -i, otherwise the tool will choose one.
</li><li>Specify --soft if you don't want the key pair to be generated on card.
</li><li>Specify the usage of the private key with -u; if you add a
corresponding certificate later, it should have the same key usage.
(Do "pkcs15-init -u help" for help).
</li><li>Specify the label (name) of the private key with -l, or accept the default
label.
</li><li>Specify the label (name) of the public key with --public-key-label, or
accept the default label.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><p>
NOTE: see the SSL engines (below) on how to make a certificate request with
the key you generated.
</p>
<h2>Add a private key</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -S <keyfile> {-f <keyformat>} -a <AuthID> --insecure
{-i <ID>} {-u <keyusage>} {--passphrase <password>}
{-l <label>}
</pre><ul><li>The keyfile should be in DER (binary) or PEM format.
</li><li>The keyformat should be PEM (default) or DER.
</li><li>Specify the AuthID of the PIN that protects the private key (from being used
in a signature or decryption operation) with -a; or specify --insecure if
you want the private key to be used without first providing a PIN
</li><li>Specify the ID of the key with -i
</li><li>Specify the usage of the private key with -u; if you add a
corresponding certificate later, it should have the same key usage.
(Do "pkcs15-init -u help" for help).
</li><li>Specify the label (name) of the with -l, or accept the default label if
you don't do so.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h2>Add a private key + certificate(s) (in a pkcs12 file)</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -S <pkcs12file> -f PKCS12 -a <AuthID> {--insecure} {-i <ID>}
{-u <keyusage>} {--passphrase <password>}
{-l <privkeylabel>} {--cert-label <usercertlabel>}
</pre><p>
This adds the private key and certificate chain to the card. If a certificate
already exists in the card, it won't be added again.
</p>
<ul><li>Specify the AuthID of the PIN that protects this key (protect from being
used in a signature or decryption operation) with -a; or specify --insecure
if you want the private key to be used without first providing a PIN.
</li><li>Specify the ID of the key and the corresponding certificate with -i,
otherwise the tool with choose one; only the 'user cert' will get the same
ID as the key,
the other certificates will get 'authority' status and another ID.
</li><li>You can specify the key-usage, but it is advised not to do this so the key
usage is fetched from the certificate.
</li><li>Specify the password of the pkcs12 key file if you don't want to be prompted
for one.
</li><li>Specify the label (name) of the private key with -l, or accept the default
label if you don't do so.
</li><li>Specify the label (name) of the user certificate with --cert-label, or
accept the default label if you don't do so.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h2>Add a certificate</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -W <certfile> {-f <certformat>} {-i <ID>} {--authority}
</pre><ul><li>The certfile should be in DER (binary) or PEM format
</li><li>The certformat should be PEM (default) or DER
</li><li>Specify the ID of the certificate with -i, otherwise the tool with choose
one; if the certificate corresponds to a private and/or public key, you
should specify the same ID as that key.
</li><li>Specify --authority if it is a CA certificate.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h2>Add a public key</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init --store-public-key <keyfile> {-f <keyformat>} {-i <ID>}
{-l <label>}
</pre><ul><li>The keyfile should be in DER (binary) or PEM format
</li><li>The keyformat should be PEM (default) or DER
</li><li>Specify the ID of the key with -i, otherwise the tool with choose one;
if the key corresponds to a private key and/or certificate, you should
specify the same ID as that private key and/or certificate.
</li><li>Specify the label (name) of the with -l, or accept the default label if
you don't do so.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h2>Add data</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -W <datafile> {-i <ID>} {-l <label>}
</pre><ul><li>The datafile is stored "as is" onto the card.
</li><li>Specify the ID of the data with -i, or accept the default ID.
</li><li>Specify the label (name) of the data with -l, or accept the default label.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h2>Update a certificate</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -U <certfile> -f <format> -i <ID> {-a <pinid>}
</pre><ul><li>Specify path to the cert file with -U, default format = PEM
</li><li>Specify the cert format (DER or PEM) with -f
</li><li>Specify the ID of the cert with -i.
</li><li>Specify the ID of the PIN needed to update the cert file (and if needed
to delete it and create and write a new one) with -a.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li><li><strong>NOTE</strong>: if the new cert is bigger then the old one, the tool will try to delete
the old cert file and create a new one. This won't work for most card
(probably SetCOS 4.4.1 is the only one where it works..)
</li></ul><h2>Change attributes (currently only the label)</h2>
<pre class="wiki" xml:space="preserve"> pkcs15-init -A <type> -i <ID> -l <label> {-a <pinid>}
</pre><p>
This allows you to modify the label of a certain PKCS15 object.
</p>
<ul><li>The type of the object should be one of the following: privkey, pubkey, cert, data.
</li><li>Specify the ID of the object with -i.
</li><li>Specify the new label with -l.
</li><li>Specify the ID of the PIN needed to update the corresponding PKCS15 file with -a.
</li><li>Depending on your card and profile option, you will be prompted to provide
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
command line with --so-pin <SOPIN> and/or --pin <PIN>.
</li></ul><h1>4. Other tools</h1>
<h2>SSL-engines</h2>
<p>
These libraries can be loaded in OpenSSL so you can do a certificate request
with the openssl tool; the signature of the certificate request will then be
made using the smart card. The result can then be sent to a CA for
certification or the resulting certificate can be put on the card with pkcs15-init
or pkcs11-tool.
</p>
<ul><li>Run openssl
</li><li>On the openssl command prompt, type
<pre class="wiki" xml:space="preserve"> engine dynamic -pre SO_PATH:engine_pkcs11 -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD
</pre>to use the PKCS #11 engine
</li><li>Then type (on the openssl command prompt)
<pre class="wiki" xml:space="preserve"> req -engine pkcs11 -new -key <ID> -keyform engine -out <cert_req>
</pre>in which ID is the slot+ID in the following format:
[slot_<slotID>][-][id_<ID>], e.g. id_45 or slot_0-id_45
</li></ul><h2>pkcs11-tool and Mozilla/Netscape</h2>
<p>
You can use the OpenSC pkcs11 library to generate a key pair in Mozilla or
Netscape, and let the browser generate a certificate request that is sent
to an on-line CA to issue and send your a certificate that is then added to the
card.
</p>
<p>
Just go to an online CA (Globalsign, Thawte, ...) and follow their guidelines.
Because such a request either costs you or at least requires you to provide a
valid mail address, it is advisable to first try you card with
"pkcs11-tool --moz-cert <cert_file_in_der_format> --login".
</p>
<p>
NOTE: This can only be done with the onepin profile option (because the browser
won't ask for an SO PIN, only for the user PIN).
</p>
<h1>5. Card-specific issues</h1>
<blockquote>
<blockquote>
<blockquote>
<p>
Experience is that marvelous thing that enables you to recognize
a mistake when you make it again. -- Franklin P. Jones
</p>
</blockquote>
</blockquote>
</blockquote>
<p>
Cryptoflex:
</p>
<ul><li>DFs and EFs in a DF have to be deleted in reverse order of creation.
OpenSC relies on this fact for security, but also has some downsides. For
example, if you did a "pkcs15-init -C" and then added some EFs or DFs in the
MF, you won't be able to do a "pkcs15-init -E" afterwards to remove the
PKCS15 DF (5015). So you'll first have to manually remove all EFs/DFs you
created in the MF before being able remove the pkcs15 DF.
</li></ul><p>
Starcos SPK 2.3:
</p>
<ul><li>Due to the way Starcos SPK 2.3 manages access rights it is necessary
to manually call "pkcs15-init --finalize" after card personalization
if no SO-PIN has been specified. Once the card has been finalized it is
not possible to add new private/secret keys or PINs. If a SO-PIN is
used the card will automatically be finalized after the SO-PIN has
been stored.
</li><li>If an SO-PIN is used and if there is enough space in the key file left,
then the owner of the SO-PIN can access/use every protected item by
creating a PIN for the necessary state.
</li></ul></div>
</div><div class="footer"><hr></hr><p><a href="index.html">Back to Index</a></p></div></body></html>