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.
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
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.
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.
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.
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 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.
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.
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.
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
--card-profile name, -c name
--generate-key keyspec, -G keyspec
pin 1234 puk 87654321
You can specify --options-file several times.
--pin, --puk --so-pin, --so-puk,
--profile name, -p name
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
--store-private-key filename, -S filename
You may additionally specify the key ID along with this command, using the --id 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 aid option.
--store-data filename, -W filename
--update-certificate filename, -U filename
Pay extra attention when updating mail decryption certificates, as missing certificates can render e-mail messages unreadable!
--delete-objects arg, -D arg
When data is specified, an ---application-id must also be specified, in the other cases an --id 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
--change-attributes arg, -A arg
pkcs15-init -A cert --id 45 -a 1 --label Jim
--reader arg, -r arg
--output-file filename -o filename,
--key-usage arg -u arg,
The alias sign is equivalent to digitalSignature,keyCertSign,cRLSign
The alias decrypt is equivalent to keyEncipherment,dataEncipherment
pkcs15-init was written by Olaf Kirch <firstname.lastname@example.org>.