Provided by: opensc_0.11.12-1ubuntu3_i386 bug

NAME

       pkcs15-init - smart card personalization utility

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 USAGE

       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 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.

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 several 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 can also request that the card is erased
       prior to creating the PKCS #15 structure, by specifying the
       --erase-card option.

   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.

       By default, pkcs15-init will try to use the card´s on-board key
       generation facilities, if available. If the card does not support
       on-board key generation, pkcs15-init will fall back to software key
       generation.

   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 okir.pem, which is in PEM format, you would use

       pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01

       If the key is protected by a pass phrase, pkcs15-init will prompt you
       for a pass phrase to unlock the key.

       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 the use of the --id option. The current 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 if you don´t specify a key ID,
       pkcs15-init will pick just the first key template defined by the
       profile.

       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 Download
       You can also download 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 downloaded automatically
       when generating a new key, or when downloading a private key, you will
       probably use this option only very rarely.

   Certificate Download
       You can download certificates to the card using the --store-certificate
       option, which takes a filename as an argument. This file is supposed to
       contain the DER encoded X.509 certificate.

   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.  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

       --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.

       --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.

       --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.

       --store-public-key filename, -P 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-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. The file is assumed to contain the DER encoded
           certificate.

       --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
           ps(1). Therefore, you should use these options only on a secured
           system, or in an options file specified with --options-file.

       --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 --pin options.

       --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.

       --verbose, -v
           Causes pkcs15-init to be more verbose. Specify this flag several
           times to enable debug output in the OpenSC library.

SEE ALSO

       pkcs15-profile(5)