PKCS15-INITPKCS15-(1) OpenSC ToolsOpenSC Tools PKCS15-INITPKCS15-(1)NAMEpkcs15-init - smart card personalization utility
SYNOPSISpkcs15-init [OPTIONS]
DESCRIPTION
The pkcs15-init 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.
The profile used by default is pkcs15. Alternative profiles can be
specified via the -p switch.
PIN USAGEpkcs15-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 personalization.
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.
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.
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.
For each PIN, you can specify a PUK (also called unblock PIN). The PUK
can be used to overwrite or unlock a PIN if too many incorrect values
have been entered in a row.
For some cards that use the PKCS#15 emulation, the attributes of
private objects are protected and cannot be parsed without
authentication (usually with User PIN). This authentication need to be
done immediately after the card binding. In such cases --verify-pin has
to be used.
MODES OF OPERATION
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
pkcs15-init--create-pkcs15
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.
If the card supports it, you should erase the contents of the card with
pkcs15-init--erase-card before creating the PKCS#15 structure.
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
pkcs15-init--store-pin --id " nn
where nn is a PKCS #15 ID in hexadecimal notation. Common values are
01, 02, etc.
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.
To set a label for this PIN object (which can be used by applications
to display a meaningful prompt to the user), use the --label command
line option.
Key generation
pkcs15-init lets you generate a new key and store it on the card. You
can do this using:
pkcs15-init--generate-key " keyspec " --auth-id " nn
where keyspec describes the algorithm and length of the key to be
created, such as 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.
nn is the ID of a user PIN installed previously, e.g. 01.
In addition to storing the private portion of the key on the card,
pkcs15-init will also store the the public portion of the key as a PKCS
#15 public key object.
Private Key Upload
You can use a private key generated by other means and upload it to the
card. For instance, to upload a private key contained in a file named
okir.pem, which is in PEM format, you would use
pkcs15-init--store-private-key okir.pem --id 45 --auth-id 01
In addition to storing the private portion of the key on the card,
pkcs15-init will also store the the public portion of the key as a PKCS
#15 public key object.
Note that usage of --id option in the pkcs15-init commands to generate
or to import a new key is deprecated. Better practice is to let the
middleware to derive the identifier from the key material.
(SHA1(modulus) for RSA, SHA1(pub) for DSA, ...). This allows easily set
up relation between 'related' objects (private/public keys and
certificates).
In addition to the PEM key file format, pkcs15-init 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, pkcs15-init will
store the certificate instead of the public key portion.
Public Key Upload
You can also upload individual public keys to the card using the
--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 --format option, pkcs15-init will assume PEM
format. The only other supported public key file format is DER.
Since the corresponding public keys are always uploaded automatically
when generating a new key, or when uploading a private key, you will
probably use this option only very rarely.
Certificate Upload
You can upload certificates to the card using the --store-certificate
option, which takes a filename as an argument. This file is supposed to
contain the PEM encoded X.509 certificate.
Uploading PKCS #12 bags
Most browsers nowadays use PKCS #12 format files when you ask them to
export your key and certificate to a file. pkcs15-init 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:
pkcs15-init--store-private-key okir.p12 --format pkcs12 --auth-id 01
This will install the private key contained in the file okir.p12, and
protect it with the PIN referenced by authentication ID 01. 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.
OPTIONS--card-profile name, -c name
Tells pkcs15-init to load the specified card profile option. You
will rarely need this option.
--create-pkcs15, -C
This tells pkcs15-init to create a PKCS #15 structure on the card,
and initialize any PINs.
--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,
pkcs15-init will fail.
--generate-key keyspec, -G keyspec
Tells the card to generate new key and store it on the card.
keyspec consists of an algorithm name (currently, the only
supported name is 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 id option, otherwise an
intrinsic ID will be calculated from the key material. Look the
description of the 'pkcs15-id-style' attribut in the
'pkcs15.profile' for the details about the algorithm used to
calculate intrinsic ID. For the multi-application cards the target
PKCS#15 application can be specified by the hexadecimal AID value
of the aid option.
--options-file filename
Tells pkcs15-init to read additional options from filename. The
file is supposed to contain one long option per line, without the
leading dashes, for instance:
pin frank
puk zappa
You can specify --options-file several times.
--pin, --puk --so-pin, --so-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
ps(1). Therefore, you should use these options only on a secured
system, or in an options file specified with --options-file.
--profile name, -p name
Tells pkcs15-init to load the specified general profile. Currently,
the only application profile defined is pkcs15, but you can write
your own profiles and specify them using this option.
The profile name can be combined with one or more profile options,
which slightly modify the profile's behavior. For instance, the
default OpenSC profile supports the openpin 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 + character, as in
pkcs15+onepin.
--store-certificate filename, -X filename
Tells pkcs15-init to store the certificate given in filename on the
card, creating a certificate object with the ID specified via the
--id option. Without supplied ID an intrisic ID will be calculated
from the certificate's public key. Look the description of the
'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID. The file is
assumed to contain the PEM encoded certificate. For the
multi-application cards the target application can be specified by
the hexadecimal AID value of the aid option.
--store-public-key filename
Tells pkcs15-init to download the specified public key to the card
and create a public key object with the key ID specified via the
--id. By default, the file is assumed to contain the key in PEM
format. Alternative formats can be specified using --format.
--store-private-key filename, -S filename
Tells pkcs15-init 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
--format. It is a good idea to specify the key ID along with this
command, using the --id option, otherwise an intrinsic ID will be
calculated from the key material. Look the description of the
'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID. For the
multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the aid option.
--update-certificate filename, -U filename
Tells pkcs15-init to update the certificate object with the ID
specified via the --id option with the certificate in filename. The
file is assumed to contain a PEM encoded certificate.
Pay extra attention when updating mail decryption certificates, as
missing certificates can render e-mail messages unreadable!
--use-default-transport-keys, -T
Tells pkcs15-init to not ask for the transport keys and use default
keys, as known by the card driver.
--verbose, -v
Causes pkcs15-init to be more verbose. Specify this flag several
times to enable debug output in the OpenSC library.
SEE ALSOpkcs15-profile(5)openscopensc 02/09/2014 PKCS15-INITPKCS15-(1)
