Unix/Linux Go Back    


CentOS 7.0 - man page for pkcs15-init (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PKCS15-INITPKCS15-(1)		     OpenSC ToolsOpenSC Tools		    PKCS15-INITPKCS15-(1)

NAME
       pkcs15-init - smart card personalization utility

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

       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 ALSO
       pkcs15-profile(5)

openscopensc				    06/17/2014			    PKCS15-INITPKCS15-(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:37 PM.