Provided by: opensc_0.10.1-1_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
       namedokir.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 currentpkcs15 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  ispkcs15,  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 theopenpin 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)

                                                                PKCS15-INIT(1)