282 lines
10 KiB
Groff
282 lines
10 KiB
Groff
.PU
|
|
.ds nm \fBpkcs15-init\fR
|
|
.TH pkcs15-init 1 "" "" OpenSC
|
|
.SH NAME
|
|
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.
|
|
.PP
|
|
The profile used by default is \fBpkcs15\fR. Alternative
|
|
profiles can be specified via the \fB-p\fR switch.
|
|
.SH PIN Usage
|
|
.B pkcs15-init
|
|
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\fP.
|
|
.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\fP). 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
|
|
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
|
|
.B " pkcs15-init --create-pkcs15
|
|
.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
|
|
.B --erase-card
|
|
option.
|
|
.SS User PIN Installation
|
|
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
|
|
.BI " pkcs15-init --store-pin --id " nn
|
|
.PP
|
|
where \fInn\fP is a PKCS #15 ID in hexadecimal notation. Common values
|
|
are \fB01\fP, \fB02\fP, 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\fP command line 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 " --auth-id " nn
|
|
.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
|
|
\fInn\fP is the ID of a user PIN installed previously, e.g. \fB01\fP.
|
|
.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
|
|
By default, \*(nm will try to use the card's on-board key
|
|
generation facilities, if available. If the card does not
|
|
support on-board key generation, \*(nm will fall back to
|
|
software key generation.
|
|
.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 --auth-id 01
|
|
.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. A PKCS #12 file usually contains the X.509 certificate
|
|
corresponding to the private key. If that is the case,
|
|
\*(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.
|
|
.SS Downloading PKCS #12 bags
|
|
Most browsers nowadays use PKCS #12 format files when you ask them to
|
|
export your key and certificate to a file. \*(nm 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
|
|
.nf
|
|
.BI " pkcs15-init --store-private-key okir.p12 --format pkcs12
|
|
.BI " --auth-id 01
|
|
.fi
|
|
This will install the private key contained in the file \fBokir.p12\fP,
|
|
and protected it with the PIN referenced by authentication ID \fB01\fP.
|
|
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
|
|
.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.
|
|
.IP
|
|
The profile name can be combined with one or more \fIprofile options\fP,
|
|
which slightly modify the profile's behavior. For instance, the
|
|
default OpenSC profile supports the \fBopenpin\fP 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.
|
|
.IP
|
|
Profile name and options are separated by a \fB+\fP character,
|
|
as in \fBpkcs15+onepin\fP.
|
|
.TP
|
|
.BR \-\-card-profile " \fIname\fP, " \-c " \fIname\fP"
|
|
Tells \*(nm to load the specified card profile option.
|
|
You will rarely need this 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 \-\-so-pin ", " \-\-so-puk ", " \-\-pin ", " \-\-puk
|
|
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
|
|
.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
|
|
pin frank
|
|
puk zappa
|
|
.fi
|
|
.PP
|
|
You can specify
|
|
.B \-\-options-file
|
|
several times.
|
|
.TP
|
|
.BR \-\-verbose ", " \-v
|
|
Causes \*(nm to be more verbose. Specify this flag several times
|
|
to enable debug output in the opensc library.
|
|
.SH SEE ALSO
|
|
.BR pkcs15-profile (5) .
|
|
.SH BUGS
|
|
This manual page is usually out of date. Please cross-check options
|
|
using the \fB--help\fP option.
|
|
.SH AUTHORS
|
|
\*(nm was written by Olaf Kirch <okir@lst.de>
|