417 lines
15 KiB
XML
417 lines
15 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<refentry id="">
|
|
<refmeta>
|
|
<refentrytitle>pkcs15-init</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>opensc</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pkcs15-init</refname>
|
|
<refpurpose>smart card personalization utility</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
The <command>pkcs15-init</command> 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.
|
|
</para>
|
|
<para>
|
|
The profile used by default is <command>pkcs15</command>. Alternative
|
|
profiles can be specified via the <option>-p</option> switch.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>PIN Usage</title>
|
|
<para>
|
|
<command>pkcs15-init</command> 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 <emphasis>personalization</emphasis>.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
For each PIN, you can specify a PUK (also called <emphasis>unblock PIN</emphasis>).
|
|
The PUK can be used to overwrite or unlock a PIN if too many incorrect values
|
|
have been entered in a row.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Modes of operation</title>
|
|
<refsect2>
|
|
<title>Initialization</title>
|
|
<para>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
|
|
</para>
|
|
<para>
|
|
<command>pkcs15-init --create-pkcs15</command></para>
|
|
<para>
|
|
You will then be asked for the security officer PIN and PUK. Simply
|
|
pressing return at the SO PIN prompt will skip installation of an SO PIN.
|
|
</para>
|
|
<para>
|
|
If the card supports it, you should erase the contents of the card with
|
|
<command>pkcs15-init --erase-card</command> before creating the PKCS#15 structure.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>User PIN Installation</title>
|
|
<para>
|
|
Before installing any user objects such as private keys, you need at least one
|
|
PIN to protect these objects. you can do this using
|
|
</para>
|
|
<para>
|
|
<command>pkcs15-init --store-pin --id " nn</command>
|
|
</para>
|
|
<para>
|
|
where <emphasis>nn</emphasis> is a PKCS #15 ID in hexadecimal notation. Common
|
|
values are 01, 02, etc.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
To set a label for this PIN object (which can be used by applications to display
|
|
a meaningful prompt to the user), use the <option>--label</option> command line option.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Key generation</title>
|
|
<para>
|
|
<command>pkcs15-init</command> lets you generate a new key and store it on the card.
|
|
You can do this using:
|
|
</para>
|
|
<para>
|
|
<command>pkcs15-init --generate-key " keyspec " --auth-id " nn</command>
|
|
</para>
|
|
<para>
|
|
where <option>keyspec</option> describes the algorithm and length of the
|
|
key to be created, such as <option>rsa/512</option>. 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.
|
|
</para>
|
|
<para>
|
|
<option>nn</option> is the ID of a user PIN installed previously, e.g. 01.
|
|
</para>
|
|
<para>
|
|
In addition to storing the private portion of the key on the card,
|
|
<command>pkcs15-init</command> will also store the the public portion of the
|
|
key as a PKCS #15 public key object.
|
|
</para>
|
|
<para>
|
|
By default, <command>pkcs15-init</command> will try to use the card's
|
|
on-board key generation facilities, if available. If the card does not
|
|
support on-board key generation, <command>pkcs15-init</command> will fall
|
|
back to software key generation.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Private Key Download</title>
|
|
<para>
|
|
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
|
|
<emphasis>okir.pem</emphasis>, which is in PEM format, you would use
|
|
</para>
|
|
<para>
|
|
<command>pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01</command>
|
|
</para>
|
|
<para>
|
|
If the key is protected by a pass phrase, <command>pkcs15-init</command>
|
|
will prompt you for a pass phrase to unlock the key.
|
|
</para>
|
|
<para>
|
|
In addition to storing the private portion of the key on the card,
|
|
<command>pkcs15-init</command> will also store the the public portion of the
|
|
key as a PKCS #15 public key object.
|
|
</para>
|
|
<para>
|
|
Note the use of the <option>--id</option> option. The current
|
|
<command>pkcs15</command> 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, <command>pkcs15-init</command> will pick just the first key
|
|
template defined by the profile.
|
|
</para>
|
|
<para>
|
|
In addition to the PEM key file format, <command>pkcs15-init</command> 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, <command>pkcs15-init</command> will
|
|
store the certificate instead of the public key portion.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Public Key Download</title>
|
|
<para>
|
|
You can also download individual public keys to the card using the
|
|
<option>--store-public-key</option> 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 <option>--format</option> option,
|
|
<command>pkcs15-init</command> will assume PEM format. The only other
|
|
supported public key file format is DER.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Certificate Download</title>
|
|
<para>
|
|
You can download certificates to the card using the
|
|
<option>--store-certificate</option> option, which takes a filename as
|
|
an argument. This file is supposed to contain the PEM encoded X.509
|
|
certificate.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Downloading PKCS #12 bags</title>
|
|
<para>
|
|
Most browsers nowadays use PKCS #12 format files when you ask them to
|
|
export your key and certificate to a file. <command>pkcs15-init</command>
|
|
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:
|
|
</para>
|
|
<para>
|
|
<command>pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id
|
|
01</command>
|
|
</para>
|
|
<para>
|
|
This will install the private key contained in the file <emphasis>okir.p12</emphasis>,
|
|
and protect it with the PIN referenced by authentication ID <emphasis>01</emphasis>.
|
|
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.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--profile</option> <emphasis>name</emphasis>,
|
|
<option>-p</option> <emphasis>name</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to load the specified general
|
|
profile. Currently, the only application profile defined is
|
|
<command>pkcs15</command>, but you can write your own profiles and
|
|
specify them using this option.
|
|
</para>
|
|
<para>
|
|
The profile name can be combined with one or more <emphasis>profile
|
|
options</emphasis>, which slightly modify the profile's behavior.
|
|
For instance, the default OpenSC profile supports the
|
|
<option>openpin</option> 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.
|
|
</para>
|
|
<para>
|
|
Profile name and options are separated by a <option>+</option>
|
|
character, as in <option>pkcs15+onepin</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--card-profile</option> <emphasis>name</emphasis>,
|
|
<option>-c</option> <emphasis>name</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to load the specified card
|
|
profile option. You will rarely need this option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--create-pkcs15, -C</option></term>
|
|
<listitem>
|
|
<para>
|
|
This tells <command>pkcs15-init</command> to create a PKCS #15
|
|
structure on the card, and initialize any PINs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--erase-card, -E</option></term>
|
|
<listitem>
|
|
<para>
|
|
This will erase the card prior to creating the PKCS #15 structure,
|
|
if the card supports it. If the card does not support erasing,
|
|
<command>pkcs15-init</command> will fail.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--generate-key</option> <emphasis>keyspec</emphasis>,
|
|
<option>-G</option> <emphasis>keyspec</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells the card to generate new key and store it on the card.
|
|
<emphasis>keyspec</emphasis> consists of an algorithm name
|
|
(currently, the only supported name is <option>RSA</option>),
|
|
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 <option>id</option> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--store-private-key</option> <emphasis>filename</emphasis>,
|
|
<option>-S</option> <emphasis>filename</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> 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 <option>--format</option>.
|
|
It is a good idea to specify the key ID along with this command,
|
|
using the <option>--id</option> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--store-public-key</option> <emphasis>filename</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to download the specified
|
|
public key to the card and create a public key object with the
|
|
key ID specified via the <option>--id</option>. By default,
|
|
the file is assumed to contain the key in PEM format. Alternative
|
|
formats can be specified using <option>--format</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--store-certificate</option> <emphasis>filename</emphasis>,
|
|
<option>-X</option> <emphasis>filename</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to store the certificate given
|
|
in <option>filename</option> on the card, creating a certificate
|
|
object with the ID specified via the <option>--id</option> option.
|
|
The file is assumed to contain the PEM encoded certificate.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--use-default-transport-keys</option>,
|
|
<option>-T</option></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to not ask for the transport
|
|
keys and use default keys, as known by the card driver.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--so-pin, --so-puk, --pin, --puk</option></term>
|
|
<listitem>
|
|
<para>
|
|
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 <command>ps(1)</command>. Therefore, you should use these options
|
|
only on a secured system, or in an options file specified with
|
|
<option>--options-file</option>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--passphrase</option></term>
|
|
<listitem>
|
|
<para>
|
|
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 <option>--pin</option> options.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--options-file</option> <emphasis>filename</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
Tells <command>pkcs15-init</command> to read additional options
|
|
from <emphasis>filename</emphasis>. The file is supposed to
|
|
contain one long option per line, without the leading dashes,
|
|
for instance:
|
|
<programlisting>
|
|
pin frank
|
|
puk zappa
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
You can specify <option>--options-file</option> several times.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--verbose, -v</option></term>
|
|
<listitem>
|
|
<para>
|
|
Causes <command>pkcs15-init</command> to be more verbose. Specify this
|
|
flag several times to enable debug output in the OpenSC library.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
<para>pkcs15-profile(5)</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|