'\" t
.\"     Title: pkcs15-initpkcs15-init
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/30/2018
.\"    Manual: OpenSC ToolsOpenSC Tools
.\"    Source: openscopensc
.\"  Language: English
.\"
.TH "PKCS15\-INITPKCS15\-" "1" "09/30/2018" "openscopensc" "OpenSC ToolsOpenSC Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pkcs15-init \- smart card personalization utility
.SH "SYNOPSIS"
.HP \w'\fBpkcs15\-init\fR\ 'u
\fBpkcs15\-init\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.PP
The
\fBpkcs15\-init\fR
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"
.PP
\fBpkcs15\-init\fR
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\fR\&.
.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\fR)\&. The PUK can be used to overwrite or unlock a PIN if too many incorrect values have been entered in a row\&.
.PP
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
\fB\-\-verify\-pin\fR
has to be used\&.
.SH "MODES OF OPERATION"
.SS "Initialization"
.PP
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
\fBpkcs15\-init \-\-create\-pkcs15\fR
.PP
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\&.
.PP
If the card supports it, you should erase the contents of the card with
\fBpkcs15\-init \-\-erase\-card\fR
before creating the PKCS#15 structure\&.
.SS "User PIN Installation"
.PP
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
\fBpkcs15\-init \-\-store\-pin \-\-id " nn\fR
.PP
where
\fInn\fR
is a PKCS #15 ID in hexadecimal notation\&. Common values are 01, 02, etc\&.
.PP
Entering the command above will ask you for the user\*(Aqs 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\fR
command line option\&.
.SS "Key generation"
.PP
\fBpkcs15\-init\fR
lets you generate a new key and store it on the card\&. You can do this using:
.PP
\fBpkcs15\-init \-\-generate\-key " keyspec " \-\-auth\-id " nn\fR
.PP
where
\fIkeyspec\fR
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\&.
.PP
\fInn\fR
is the ID of a user PIN installed previously, e\&.g\&.
01\&.
.PP
In addition to storing the private portion of the key on the card,
\fBpkcs15\-init\fR
will also store the the public portion of the key as a PKCS #15 public key object\&.
.SS "Private Key Upload"
.PP
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
.PP
\fBpkcs15\-init \-\-store\-private\-key okir\&.pem \-\-id 45 \-\-auth\-id 01\fR
.PP
In addition to storing the private portion of the key on the card,
\fBpkcs15\-init\fR
will also store the the public portion of the key as a PKCS #15 public key object\&.
.PP
Note that usage of
\fB\-\-id\fR
option in the
\fBpkcs15\-init\fR
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 \*(Aqrelated\*(Aq objects (private/public keys and certificates)\&.
.PP
In addition to the PEM key file format,
\fBpkcs15\-init\fR
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,
\fBpkcs15\-init\fR
will store the certificate instead of the public key portion\&.
.SS "Public Key Upload"
.PP
You can also upload individual public keys to the card using the
\fB\-\-store\-public\-key\fR
option, which takes a filename as an argument\&. This file is supposed to contain the public key\&. If you don\*(Aqt specify a key file format using the
\fB\-\-format\fR
option,
\fBpkcs15\-init\fR
will assume PEM format\&. The only other supported public key file format is DER\&.
.PP
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\&.
.SS "Certificate Upload"
.PP
You can upload certificates to the card using the
\fB\-\-store\-certificate\fR
option, which takes a filename as an argument\&. This file is supposed to contain the PEM encoded X\&.509 certificate\&.
.SS "Uploading PKCS #12 bags"
.PP
Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file\&.
\fBpkcs15\-init\fR
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
\fBpkcs15\-init \-\-store\-private\-key okir\&.p12 \-\-format pkcs12 \-\-auth\-id 01\fR
.PP
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\&.
.SH "OPTIONS"
.PP
.PP
\fB\-\-version\fR,
.RS 4
Print the OpenSC package release version\&.
.RE
.PP
\fB\-\-card\-profile\fR \fIname\fR, \fB\-c\fR \fIname\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to load the specified card profile option\&. You will rarely need this option\&.
.RE
.PP
\fB\-\-create\-pkcs15\fR, \fB\-C\fR
.RS 4
This tells
\fBpkcs15\-init\fR
to create a PKCS #15 structure on the card, and initialize any PINs\&.
.RE
.PP
\fB\-\-erase\-card\fR, \fB\-E\fR
.RS 4
This will erase the card prior to creating the PKCS #15 structure, if the card supports it\&. If the card does not support erasing,
\fBpkcs15\-init\fR
will fail\&.
.RE
.PP
\fB\-\-generate\-key\fR \fIkeyspec\fR, \fB\-G\fR \fIkeyspec\fR
.RS 4
Tells the card to generate new key and store it on the card\&.
\fIkeyspec\fR
consists of an algorithm name (currently, the only supported name is
\fBRSA\fR), 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
\fBid\fR
option, otherwise an intrinsic ID will be calculated from the key material\&. Look the description of the \*(Aqpkcs15\-id\-style\*(Aq attribut in the \*(Aqpkcs15\&.profile\*(Aq 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
\fBaid\fR
option\&.
.RE
.PP
\fB\-\-options\-file\fR \fIfilename\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to read additional options from
\fIfilename\fR\&. The file is supposed to contain one long option per line, without the leading dashes, for instance:
.sp
.if n \{\
.RS 4
.\}
.nf
	pin		frank
	puk		zappa
.fi
.if n \{\
.RE
.\}
.sp
You can specify
\fB\-\-options\-file\fR
several times\&.
.RE
.PP
\fB\-\-pin\fR, \fB\-\-puk\fR \fB\-\-so\-pin\fR, \fB\-\-so\-puk\fR,
.RS 4
These options can be used to specify PIN/PUK values on the command line\&. If set to env:\fIVARIABLE\fR, the value of the environment variable
\fIVARIABLE\fR
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
\fBps(1)\fR\&. Therefore, you should use these options only on a secured system, or in an options file specified with
\fB\-\-options\-file\fR\&.
.RE
.PP
\fB\-\-profile\fR \fIname\fR, \fB\-p\fR \fIname\fR
.RS 4
Tells
\fBpkcs15\-init\fR
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\&.
.sp
The profile name can be combined with one or more profile options, which slightly modify the profile\*(Aqs behavior\&. For instance, the default OpenSC profile supports the
\fBopenpin\fR
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\&.
.sp
Profile name and options are separated by a
+
character, as in
pkcs15+onepin\&.
.RE
.PP
\fB\-\-store\-certificate\fR \fIfilename\fR, \fB\-X\fR \fIfilename\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to store the certificate given in
\fBfilename\fR
on the card, creating a certificate object with the ID specified via the
\fB\-\-id\fR
option\&. Without supplied ID an intrisic ID will be calculated from the certificate\*(Aqs public key\&. Look the description of the \*(Aqpkcs15\-id\-style\*(Aq attribut in the \*(Aqpkcs15\&.profile\*(Aq 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
\fBaid\fR
option\&.
.RE
.PP
\fB\-\-store\-public\-key\fR \fIfilename\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to download the specified public key to the card and create a public key object with the key ID specified via the
\fB\-\-id\fR\&. By default, the file is assumed to contain the key in PEM format\&. Alternative formats can be specified using
\fB\-\-format\fR\&.
.RE
.PP
\fB\-\-store\-private\-key\fR \fIfilename\fR, \fB\-S\fR \fIfilename\fR
.RS 4
Tells
\fBpkcs15\-init\fR
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
\fB\-\-format\fR\&. It is a good idea to specify the key ID along with this command, using the
\fB\-\-id\fR
option, otherwise an intrinsic ID will be calculated from the key material\&. Look the description of the \*(Aqpkcs15\-id\-style\*(Aq attribut in the \*(Aqpkcs15\&.profile\*(Aq 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
\fBaid\fR
option\&.
.RE
.PP
\fB\-\-update\-certificate\fR \fIfilename\fR, \fB\-U\fR \fIfilename\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to update the certificate object with the ID specified via the
\fB\-\-id\fR
option with the certificate in
\fBfilename\fR\&. The file is assumed to contain a PEM encoded certificate\&.
.sp
Pay extra attention when updating mail decryption certificates, as missing certificates can render e\-mail messages unreadable!
.RE
.PP
\fB\-\-use\-default\-transport\-keys\fR, \fB\-T\fR
.RS 4
Tells
\fBpkcs15\-init\fR
to not ask for the transport keys and use default keys, as known by the card driver\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Causes
\fBpkcs15\-init\fR
to be more verbose\&. Specify this flag several times to enable debug output in the OpenSC library\&.
.RE
.SH "SEE ALSO"
.PP
\fBpkcs15-profile\fR(5)