205 lines
7.0 KiB
Groff
205 lines
7.0 KiB
Groff
.PU
|
|
.ds nm \fBpkcs15-init\fR
|
|
.TH pkcs15-init 1 "" "" OpenSC
|
|
pkcs15-init \- smart card personalization utility
|
|
.SH DESCRIPTION
|
|
The \*(nm(1) 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. When invoking \*(nm,
|
|
the user must specify the application profile using the
|
|
.B \-p
|
|
switch. Currently, there is only one supported profile,
|
|
which is
|
|
.BR pkcs15 .
|
|
.SH MODES OF OPERATION
|
|
.SS Initialization
|
|
This is the first step during card personalization, and
|
|
will create the basic files on the card, and initialize
|
|
user PINs. To create the initial PKCS #15 structure,
|
|
invoke the utility as
|
|
.PP
|
|
.B " pkcs15-init --create-pkcs15
|
|
.PP
|
|
You will then be asked for several PINs (secret codes used to protect
|
|
e.g. keys stored on the card), and PUKs. PUKs are secret codes that can
|
|
be used to
|
|
.I unblock
|
|
a PIN if too many incorrect values have been entered in a row.
|
|
.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
|
|
.B --erase-card
|
|
option.
|
|
.SS Key Generation
|
|
\*(nm lets you generate a new key and store it on the card.
|
|
You can do this using:
|
|
.PP
|
|
.BI " pkcs15-init --generate-key " keyspec
|
|
.PP
|
|
where
|
|
.I keyspec
|
|
describes the algorithm and length of the key to be created,
|
|
such as
|
|
.BR rsa/512 .
|
|
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
|
|
In addition to storing the private portion of the key on the
|
|
card, \*(nm will also store the the public portion of the key
|
|
as a PKCS #15 public key object.
|
|
.PP
|
|
On-board key generation is not supported at the moment.
|
|
.SS Private Key Download
|
|
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
|
|
.B okir.pem ,
|
|
which is in PEM format, you would use
|
|
.PP
|
|
.B " pkcs15-init --store-private-key okir.pem --id 45
|
|
.PP
|
|
If the key is protected by a pass phrase, \*(nm 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, \*(nm will also store the the public portion of the key
|
|
as a PKCS #15 public key object.
|
|
.PP
|
|
Note the use of the
|
|
.B --id
|
|
option. The current
|
|
.B pkcs15
|
|
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 you don't
|
|
specify a key ID, \*(nm will pick just the first key template
|
|
defined by the profile.
|
|
.PP
|
|
In addition to the PEM key file format, \*(nm 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. Since PKCS #12 files usually contains the X.509 certificate
|
|
corresponding to the private key, \*(nm will store the certificate
|
|
instead of the public key portion.
|
|
.SS Public Key Download
|
|
You can also download individual public keys to the card using
|
|
the
|
|
.B \-\-store-public-key
|
|
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
|
|
.B \-\-format
|
|
option, \*(nm 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
|
|
You can download certificates to the card using the
|
|
.B \-\-store-certificate
|
|
option, which takes a filename as an argument. This file is supposed
|
|
to contain the DER encoded X.509 certificate.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-\-profile " \fIname\fP, " \-p " \fIname\fP"
|
|
Tells \*(nm to load the specified general profile. Currently, the
|
|
only application profile defined is
|
|
.BR pkcs15 ,
|
|
but you can write your own profiles and specify them using this
|
|
option.
|
|
.TP
|
|
.BR \-\-card-profile " \fIname\fP, " \-c " \fIname\fP"
|
|
Tells \*(nm to load the specified card profile option.
|
|
.TP
|
|
.BR \-\-create-pkcs15 ", " \-C
|
|
This tells \*(nm to create a PKCS #15 structure on the card, and
|
|
initialize any PINs.
|
|
.TP
|
|
.BR \-\-erase-card ", " \-E
|
|
This will erase the card prior to creating the PKCS #15 structure,
|
|
if the card supports it. If the card does not support erasing,
|
|
\*(nm will fail.
|
|
.TP
|
|
.BR \-\-generate-key " \fIkeyspec\fP, " \-G " \fIkeyspec\fP
|
|
Tells the card to generate new key and store it on the card.
|
|
.I keyspec
|
|
consists of an algorithm name (currently, the only supported
|
|
name is
|
|
.BR RSA ),
|
|
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
|
|
.BR \-\-id " option.
|
|
.TP
|
|
.BR \-\-store-private-key " \fIfilename\fP, " -S " \fIfilename\fP"
|
|
Tells \*(nm 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
|
|
.BR \-\-format .
|
|
It is a good idea to specify the key ID along with this
|
|
command, using the
|
|
.BR \-\-id " option.
|
|
.TP
|
|
.BR \-\-store-public-key " \fIfilename\fP, " -P " \fIfilename\fP"
|
|
Tells \*(nm to download the specified public key to the card
|
|
and create a public key object with the key ID specified via the
|
|
.BR \-\-id " option.
|
|
By default, the file is assumed to contain the key in PEM format.
|
|
Alternative formats can be specified using
|
|
.BR \-\-format .
|
|
.TP
|
|
.BR \-\-store-certificate " \fIfilename\fX, " -P " \fIfilename\fP"
|
|
Tells \*(nm to store the certificate given in
|
|
.I filename
|
|
on the card, creating a certificate object with the ID specified
|
|
via the
|
|
.BR \-\-id " option. The file is assumed to contain the
|
|
DER encoded certificate.
|
|
.TP
|
|
.BR \-\-pin1 ", " \-\-pin1 ", " \-\-puk2 ", " \-\-puk2
|
|
These options can be used to specify PIN 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
|
|
.BR ps (1).
|
|
Therefore, you should use these options only on a secured
|
|
system, or in an options file specified with
|
|
.BR \-\-options-file .
|
|
.TP
|
|
.BR \-\-passphrase
|
|
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
|
|
.B \-\-pin
|
|
options.
|
|
.TP
|
|
.BI \-\-options-file " filename"
|
|
Tells \*(nm to read additional options from
|
|
.IR filename .
|
|
The file is supposed to contain one long option per line, without
|
|
the leading dashes, for instance:
|
|
.IP
|
|
.nf
|
|
pin1 frank
|
|
pin2 zappa
|
|
.fi
|
|
.PP
|
|
You can specify
|
|
.B \-\-options-file
|
|
several times.
|
|
.TP
|
|
.BR \-\-debug ", " \-d
|
|
Turns on debugging output. Specifying this option more than once
|
|
increases the verbosity of the output.
|
|
.SH SEE ALSO
|
|
.BR pkcs15-profile (5) .
|
|
.SH AUTHORS
|
|
\*(nm was written by Olaf Kirch <okir@lst.de>
|