pkcs15-init1OpenSCOpenSC Toolsopenscpkcs15-init1OpenSCOpenSC Toolsopenscpkcs15-initsmart card personalization utilitypkcs15-initOPTIONSDescription
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 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 has to be used.
Modes of operationInitializationThis 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 command line option.
Key generationpkcs15-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 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
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,
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
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.
Secret Key Upload
You can use a secret key generated by other means and upload it to the card.
For instance, to upload an AES-secret key generated by the system random generator
you would use
pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm aes/256 --auth-id 01
By default a random ID is generated for the secret key. You may specify an ID
with the if needed.
Options
,
Print the OpenSC package release version.name,
name
Tells pkcs15-init to load the specified card
profile option. You will rarely need this option.
,
This tells pkcs15-init to create a PKCS #15
structure on the card, and initialize any PINs.
SERIAL
Specify the serial number of the card.
,
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.
AID
This will erase the application with the application identifier
AID.
keyspec,
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 ),
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, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribute 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 option.
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 1234
puk 87654321
You can specify several times.
,
,
,
These options can be used to specify PIN/PUK values
on the command line. If set to
env:VARIABLE, the value
of the environment variable
VARIABLE is used. 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
.
,
Do not install a SO PIN, and do not prompt for it.
name,
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
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.
keyspec,
keyspec describes the algorithm and length of the
key to be created or downloaded, such as aes/256.
This will create a 256 bit AES key.
filename,
filename
Tells pkcs15-init to store the certificate given
in on the card, creating a certificate
object with the ID specified via the option.
Without supplied ID an intrinsic ID will be calculated from the
certificate's public key. Look the description of the 'pkcs15-id-style'
attribute 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 option.
,
Store a new PIN/PUK on the card.
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 . By default,
the file is assumed to contain the key in PEM format. Alternative
formats can be specified using .
filename,
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 .
It is a good idea to specify the key ID along with this command,
using the option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribute 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 option.
filename,
Tells pkcs15-init to download the specified
secret key to the card. The file is assumed to contain the raw key.
They key type should be specified with
option.
You may additionally specify the key ID along with this command,
using the option, otherwise a random ID is generated.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the option.
filename,
filename
Store a data object.
filename,
filename
Tells pkcs15-init to update the certificate
object with the ID specified via the 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!
arg,
arg
Tells pkcs15-init to delete the
specified object. arg
is comma-separated list containing any of
privkey, pubkey,
secrkey, cert,
chain or data.
When data is specified, an
- must also be
specified, in the other cases an
must also be specified
When chain is specified, the
certificate chain starting with the cert with
specified ID will be deleted, until there's a CA
certificate that certifies another cert on the card
arg,
arg
Tells pkcs15-init to change the
specified attribute. arg
is either privkey,
pubkey, secrkey,
cert or data.
You also have to specify the
of the object.
For now, you can only change the , e.g:
pkcs15-init -A cert --id 45 -a 1 --label Jim
,
Tells pkcs15-init to not ask for the transport
keys and use default keys, as known by the card driver.
,
Tells pkcs15-init to perform a
card specific sanity check and possibly update
procedure.
num,
num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
,
Causes pkcs15-init to be more verbose. Specify this
flag several times to enable debug output in the OpenSC library.
,
Causes pkcs15-init to
wait for a card insertion.Do not prompt the user; if no PINs supplied, pinpad will be used.ID
Specify ID of PUK to use/create
LABEL
Specify label of PUK
LABEL
Specify public key label (use with )
LABEL
Specify user cert label (use with )
arg
Specify application name of data object (use with )
AID
Specify AID of the on-card PKCS#15 application to be binded to (in hexadecimal form)
filenamefilename,
Output public portion of generated key to file
PASSPHRASE
Specify passphrase for unlocking secret key
Mark certificate as a CA certificate
argarg,
Specifies the X.509 key usage.
arg is comma-separated
list containing any of
digitalSignature,
nonRepudiation,
keyEncipherment,
dataEncipherment,
keyAgreement,
keyCertSign,
cRLSign. Abbreviated names are
allowed if unique (e.g.
dataEnc).
The alias sign is equivalent to
digitalSignature,keyCertSign,cRLSign
The alias decrypt is equivalent to
keyEncipherment,dataEncipherment
,
Finish initialization phase of the smart card
Update 'lastUpdate' attribute of tokenInfo
When storing PKCS#12 ignore CA certificates
Store or update existing certificate
Private key stored as an extractable key
Insecure mode: do not require a PIN for private key
GUID
For a new key specify GUID for a MD container
,
Display help message
See alsopkcs15-profile5Authorspkcs15-init was written by
Olaf Kirch okir@suse.de.