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
|
.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "PKCS15-INIT" 1 "" "" "OpenSC"
.SH NAME
pkcs15-init \- smart card personalization utility
.SH "DESCRIPTION"
.PP
The \fBpkcs15\-init\fR utility can be used to create a PKCS #15 structure on a smart card, and add key or certificate objects\&. Details of the structure that will be created are controlled via profiles\&.
.PP
The profile used by default is \fBpkcs15\fR\&. Alternative profiles can be specified via the \fB\-p\fR switch\&.
.SH "PIN USAGE"
.PP
\fBpkcs15\-init\fR can be used to create a PKCS #15 structure on your smart card, create PINs, and install keys and certificates on the card\&. This process is also called \fIpersonalization\fR\&.
.PP
An OpenSC card can have one security officer PIN, and zero or more user PINs\&. PIN stands for Personal Identification Number, and is a secret code you need to present to the card before being allowed to perform certain operations, such as using one of the stored RSA keys to sign a document, or modifying the card itself\&.
.PP
Usually, PINs are a sequence of decimal digits, but some cards will accept arbitrary ASCII characters\&. Be aware however that using characters other than digits will make the card unusable with PIN pad readers, because those usually have keys for entering digits only\&.
.PP
The security officer (SO) PIN is special; it is used to protect meta data information on the card, such as the PKCS #15 structure itself\&. Setting the SO PIN is optional, because the worst that can usually happen is that someone finding your card can mess it up\&. To extract any of your secret keys stored on the card, an attacker will still need your user PIN, at least for the default OpenSC profiles\&. However, it is possible to create card profiles that will allow the security officer to override user PINs\&.
.PP
For each PIN, you can specify a PUK (also called \fIunblock PIN\fR)\&. The PUK can be used to overwrite or unlock a PIN if too many incorrect values have been entered in a row\&.
.SH "MODES OF OPERATION"
.SS "Initialization"
.PP
This is the first step during card personalization, and will create the basic files on the card\&. To create the initial PKCS #15 structure, invoke the utility as
.PP
\fBpkcs15\-init \-\-create\-pkcs15\fR
.PP
You will then be asked for several the security officer PIN and PUK\&. Simply pressing return at the SO PIN prompt will skip installation of an SO PIN\&.
.PP
If the card supports it, you can also request that the card is erased prior to creating the PKCS #15 structure, by specifying the \fB\-\-erase\-card\fR option\&.
.SS "User PIN Installation"
.PP
Before installing any user objects such as private keys, you need at least one PIN to protect these objects\&. you can do this using
.PP
\fBpkcs15\-init \-\-store\-pin \-\-id " nn\fR
.PP
where \fInn\fR is a PKCS #15 ID in hexadecimal notation\&. Common values are 01, 02, etc\&.
.PP
Entering the command above will ask you for the user's PIN and PUK\&. If you do not wish to install an unblock PIN, simply press return at the PUK prompt\&.
.PP
To set a label for this PIN object (which can be used by applications to display a meaningful prompt to the user), use the \fB\-\-label\fR command line option\&.
.SS "Key generation"
.PP
\fBpkcs15\-init\fR lets you generate a new key and store it on the card\&. You can do this using:
.PP
\fBpkcs15\-init \-\-generate\-key " keyspec " \-\-auth\-id " nn\fR
.PP
where \fBkeyspec\fR describes the algorithm and length of the key to be created, such as \fBrsa/512\fR\&. This will create a 512 bit RSA key\&. Currently, only RSA key generation is supported\&. Note that cards usually support just a few different key lengths\&. Almost all cards will support 512 and 1024 bit keys, some will support 768 or 2048 as well\&.
.PP
\fBnn\fR is the ID of a user PIN installed previously, e\&.g\&. 01\&.
.PP
In addition to storing the private portion of the key on the card,\fBpkcs15\-init\fR will also store the the public portion of the key as a PKCS #15 public key object\&.
.PP
By default, \fBpkcs15\-init\fR will try to use the card's on\-board key generation facilities, if available\&. If the card does not support on\-board key generation, \fBpkcs15\-init\fR will fall back to software key generation\&.
.SS "Private Key Download"
.PP
You can use a private key generated by other means and download it to the card\&. For instance, to download a private key contained in a file named\fIokir\&.pem\fR, which is in PEM format, you would use
.PP
\fBpkcs15\-init \-\-store\-private\-key okir\&.pem \-\-id 45 \-\-auth\-id 01\fR
.PP
If the key is protected by a pass phrase, \fBpkcs15\-init\fR will prompt you for a pass phrase to unlock the key\&.
.PP
In addition to storing the private portion of the key on the card,\fBpkcs15\-init\fR will also store the the public portion of the key as a PKCS #15 public key object\&.
.PP
Note the use of the \fB\-\-id\fR option\&. The current\fBpkcs15\fR profile defines two key templates, one for authentication (key ID 45), and one for non\-repudiation purposes (key ID 46)\&. Other key templates will probably be added in the future\&. Note that if you don't specify a key ID, \fBpkcs15\-init\fR will pick just the first key template defined by the profile\&.
.PP
In addition to the PEM key file format, \fBpkcs15\-init\fR also supports DER encoded keys, and PKCS #12 files\&. The latter is the file format used by Netscape Navigator (among others) when exporting certificates to a file\&. A PKCS #12 file usually contains the X\&.509 certificate corresponding to the private key\&. If that is the case, \fBpkcs15\-init\fR will store the certificate instead of the public key portion\&.
.SS "Public Key Download"
.PP
You can also download individual public keys to the card using the\fB\-\-store\-public\-key\fR option, which takes a filename as an argument\&. This file is supposed to contain the public key\&. If you don't specify a key file format using the \fB\-\-format\fR option,\fBpkcs15\-init\fR will assume PEM format\&. The only other supported public key file format is DER\&.
.PP
Since the corresponding public keys are always downloaded automatically when generating a new key, or when downloading a private key, you will probably use this option only very rarely\&.
.SS "Certificate Download"
.PP
You can download certificates to the card using the\fB\-\-store\-certificate\fR option, which takes a filename as an argument\&. This file is supposed to contain the DER encoded X\&.509 certificate\&.
.SS "Downloading PKCS #12 bags"
.PP
Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file\&. \fBpkcs15\-init\fR is capable of parsing these files, and storing their contents on the card in a single operation\&. This works just like storing a private key, except that you need to specify the file format:
.PP
\fBpkcs15\-init \-\-store\-private\-key okir\&.p12 \-\-format pkcs12 \-\-auth\-id 01\fR
.PP
This will install the private key contained in the file \fIokir\&.p12\fR, and protect it with the PIN referenced by authentication ID \fI01\fR\&. It will also store any X\&.509 certificates contained in the file, which is usually the user certificate that goes with the key, as well as the CA certificate\&.
.SH "OPTIONS"
.PP
.TP
\fB\-\-profile\fR \fIname\fR, \fB\-p\fR \fIname\fR
Tells \fBpkcs15\-init\fR to load the specified general profile\&. Currently, the only application profile defined is\fBpkcs15\fR, but you can write your own profiles and specify them using this option\&.
The profile name can be combined with one or more \fIprofile options\fR, which slightly modify the profile's behavior\&. For instance, the default OpenSC profile supports the\fBopenpin\fR option, which installs a single PIN during card initialization\&. This PIN is then used both as the SO PIN as well as the user PIN for all keys stored on the card\&.
Profile name and options are separated by a \fB+\fR character, as in \fBpkcs15+onepin\fR\&.
.TP
\fB\-\-card\-profile\fR \fIname\fR, \fB\-c\fR \fIname\fR
Tells \fBpkcs15\-init\fR to load the specified card profile option\&. You will rarely need this option\&.
.TP
\fB\-\-create\-pkcs15, \-C\fR
This tells \fBpkcs15\-init\fR to create a PKCS #15 structure on the card, and initialize any PINs\&.
.TP
\fB\-\-erase\-card, \-E\fR
This will erase the card prior to creating the PKCS #15 structure, if the card supports it\&. If the card does not support erasing,\fBpkcs15\-init\fR will fail\&.
.TP
\fB\-\-generate\-key\fR \fIkeyspec\fR, \fB\-G\fR \fIkeyspec\fR
Tells the card to generate new key and store it on the card\&.\fIkeyspec\fR consists of an algorithm name (currently, the only supported name is \fBRSA\fR), optionally followed by a slash and the length of the key in bits\&. It is a good idea to specify the key ID along with this command, using the \fBid\fR option\&.
.TP
\fB\-\-store\-private\-key\fR \fIfilename\fR, \fB\-S\fR \fIfilename\fR
Tells \fBpkcs15\-init\fR to download the specified private key to the card\&. This command will also create a public key object containing the public key portion\&. By default, the file is assumed to contain the key in PEM format\&. Alternative formats can be specified using \fB\-\-format\fR\&. It is a good idea to specify the key ID along with this command, using the \fB\-\-id\fR option\&.
.TP
\fB\-\-store\-public\-key\fR \fIfilename\fR, \fB\-P\fR \fIfilename\fR
Tells \fBpkcs15\-init\fR to download the specified public key to the card and create a public key object with the key ID specified via the \fB\-\-id\fR\&. By default, the file is assumed to contain the key in PEM format\&. Alternative formats can be specified using \fB\-\-format\fR\&.
.TP
\fB\-\-store\-certificate\fR \fIfilename\fR, \fB\-X\fR \fIfilename\fR
Tells \fBpkcs15\-init\fR to store the certificate given in \fBfilename\fR on the card, creating a certificate object with the ID specified via the \fB\-\-id\fR option\&. The file is assumed to contain the DER encoded certificate\&.
.TP
\fB\-\-so\-pin, \-\-so\-puk, \-\-pin, \-\-puk\fR
These options can be used to specify PIN/PUK values on the command line\&. Note that on most operation systems, any user can display the command line of any process on the system using utilities such as \fBps(1)\fR\&. Therefore, you should use these options only on a secured system, or in an options file specified with\fB\-\-options\-file\fR\&.
.TP
\fB\-\-passphrase\fR
When downloading a private key, this option can be used to specify the pass phrase to unlock the private key\&. The same caveat applies here as in the case of the \fB\-\-pin\fR options\&.
.TP
\fB\-\-options\-file\fR \fIfilename\fR
Tells \fBpkcs15\-init\fR to read additional options from \fIfilename\fR\&. The file is supposed to contain one long option per line, without the leading dashes, for instance:
.nf
pin frank
puk zappa
.fi
You can specify \fB\-\-options\-file\fR several times\&.
.TP
\fB\-\-verbose, \-v\fR
Causes \fBpkcs15\-init\fR to be more verbose\&. Specify this flag several times to enable debug output in the OpenSC library\&.
.SH "SEE ALSO"
.PP
pkcs15\-profile(5)
|
