1. Introduction

Nothing is impossible for the man who doesn't have to do it himself. -- A.H. Weiler

This guide is about initialising and personalising (no distinction made) cards with the OpenSC library and tools (mostly pkcs15-init).

Some knowlegde about smart cards is assumed. Below is a short overview of some key words and concepts. For more info, see the opensc.html manual.

Filesystem - MF - DF - EF - FID

A smart cards has a non-volatile memory (EEPROM) in which usually a PC-like file system is implemented. The directories are called Dedicated Files (DF) and the files are called Elementary Files (EF). They are identified by a a File ID (FID) on 2 bytes. For example, the root of the file system (called Master File or MF) has FID = 3F 00 (hex).

Commands - APDUs

It is possible to send commands (APDUs) to the card to select, read, write, create, list, delete, ... EFs and DFs (not all cards allow all commands).

Access control, PIN, PUK

The file system usually implements some sort of access control on EFs and DFs. This is usually done by PINs or Keys: you have to provide a PIN or show knowledge of a key before you can perform some command on some EF/DF. A PIN is usually accompanied by a PUK (Pin Unblock Key), which can be used to reset (or unblock) that PIN.

Cryptographic keys

On crypto cards, it is also possible to sign, decrypt, generate a key pair (what can be done exactly depends on the card). on some cards, key and/or PINs are files in the filesystem, on other cards, they don't exist in the filesystem but are referenced through an ID.

Reader - PC/SC - OpenCT - CT-API

Smart card readers come with a library that can be used on a PC to send APDUs to the card. Commonly used APIs for those libraries are PC/SC, OpenCT and CT-API.

PKCS#15

There are standards (e.g. ISO7816, parts 4-...) that specify how to select, read, write, EFs and DFs, and how to sign, decrypt, login, ... However, there is also a need to know which files contain what, or where the keys, PINs, .. can be found.

For crypto cards, PCKS15 adresses this need by defining some files that contain info on where to find keys, certificates, PINs, and other data. For example, there is a PrKDF (Private Key Directory File) that contains the EFs or ID of the private keys, what those keys can be used for, by which PINs they are protected, ...

So a "PCKS#5 card" is nothing but any other card on which the right set of files has been added. In short: PKCS15 allows you to describe where to find PINs, keys, certificates and data on a card, plus all the info that is needed to use them.

A little PKCS!#15 example

Here's the textual contents of 3 PKCS#15 files: the AODF (Authentication Object Directory File), PrKDF (Private Key Directory File) and CDF (Certificate Directory File) that contain info on resp. the PINs, private keys and certificates. Each of them contains 1 entry.

AODF:
    Com. Flags  : private, modifiable
    Auth ID     : 01
    Flags       : [0x32], local, initialized, needs-padding
    Length      : min_len:4, max_len:8, stored_len:8
    Pad char    : 0x00
    Reference   : 1
    Encoding    : ASCII-numeric
    Path        : 3F005015

PrKDF:
    Com. Flags  : private, modifiable
    Com. Auth ID: 01
    Usage       : [0x32E], decrypt, sign, signRecover, unwrap, derive, nonRep
    Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
    ModLength   : 1024
    Key ref     : 0
    Native      : yes
    Path        : 3F00501530450012
    ID          : 45

X.509 Certificate [/C=BE/ST=...]
    Com. Flags  : modifiable
    Authority   : no
    Path        : 3f0050154545
    ID          : 45

Some things to note:

Use the pkcs15-tool --dump tool to see yourself what pkcs15 data is on your card, or opensc-explorer to browse through the files.

Have the PKCS#15 files a fixed place so everyone can find them? No, there's only one: the EF(DIR) in the MF and with ID 2F00. That's the starting place.

2. The OpenSC pkcs15-init library and profiles

Reading and writing files, PIN verification, signing and decryption happen in much the same way on all cards. Therefore, the "normal life" commands have been implemented in OpenSC for all supported cards.

However, creating and deleting files, PINs and keys is very card specific and has not yet been implemented for all cards. Currently, pkcs15-init is implemented for: Cryptoflex, Cyberflex, CardOS (etoken), GPK, Miocos, Starcos JCOP and Oberthur. (Check src/pkcs15init/pkcs15-*.c for possible updates). Because of this, and because pkcs15-init is not necessary for "normal life" operations, it has been put in a separate library and in a separate directory.

Profile

Because the initialisation/personalisation is so card-specific, it would be very hard to make a tool or API that accepts all parameters for all current and future cards. Therefore, a profile file has been made in OpenSC that contains all the card-specific parameters. This card-specific profile is read by card-specific code in the pkcs15-init library each time this library is used on that card. See the *.profile files in src/pkcs15init/. There is one general file (pkcs15.profile) and one card-specific profile for each card.

Profile options

There are currently 3 options you can specify to modify a profile:

3. pkcs15-init tool

This is a command-line tool that uses the pkcs15-init library. It allows you to do all the init/perso things, e.g. add/delete keys, certificates, PINs and data, generate keys, ... while specifying key usage, which PIN protects which key, ...

As said before, not all cards are supported in the pkcs15-init library. In that case, the pkcs15-init tool won't work (top 5 questions on the mailing list :-). To find out which card you have, try "opensc-tool -n"

Below is explained how to do the operations that are supported by pkcs15-tool. Not all options are explained (run "pkcs15-tool -h" to see them) because some are card-specific or obsolete (or we don't know about them). Feel free to experiment and explain them here.

So the things in this section are fairly general but not guaranteed to work for all cards. See also the section on "card-specific issues".

The --reader or -r can be given with any command. By default the first reader is used. Do "opensc-tool -l" to see the list of available readers.

To see the results of what you did, you can do one of the following:

   pkcs15-tool --list-pins --list-public-keys -k -c -C
   pkcs15-tool --dump

To see/dump the content of any file, use the opensc-explorer tool.

Create the PKCS15 files

      pkcs15-init -C {-T} {-p <profile>}
         --so-pin <PIN> --so-puk <PUK> | --no-so-pin | --pin <PIN> --puk <PUK>

This will create the PKCS15 DF (5015) and all the PKCS15 files (some of which will be empty until a key, PIN, ... will be added). It must be done before you can do any of the operations below.

Erase the card's content

      pkcs15-init -E {-T}

This will delete all keys, PINs, certificates, data that were listed in PKCS15 files, along with the PKCS15 files themselves.

Note: you can combine erase/create (-E -C or -EC) to erase and then create the card's contents, except when you change the profile option.

Add a PIN (not possible with the onepin profile option)

      pkcs15-init -P {-a <AuthID>} {--pin <PIN>} {--puk <PUK>} {-l <label>}

Generate a key pair (on card or in software on the PC)

      pkcs15-init -G <keyspec> -a <AuthID> --insecure {-i <ID>} {--soft}
                  {-u <keyusage>}
                  {-l <privkeylabel>} {--public-key-label <pubkeylabel>}

This will generate a public and private key pair.

NOTE: see the SSL engines (below) on how to make a certificate request with the key you generated.

Add a private key

      pkcs15-init -S <keyfile> {-f <keyformat>} -a <AuthID> --insecure
                  {-i <ID>} {-u <keyusage>} {--passphrase <password>}
                  {-l <label>}

Add a private key + certificate(s) (in a pkcs12 file)

      pkcs15-init -S <pkcs12file> -f PKCS12 -a <AuthID> {--insecure} {-i <ID>}
        {-u <keyusage>} {--passphrase <password>}
        {-l <privkeylabel>} {--cert-label <usercertlabel>}

This adds the private key and certificate chain to the card. If a certificate already exists in the card, it won't be added again.

Add a certificate

      pkcs15-init -W <certfile> {-f <certformat>} {-i <ID>} {--authority}

Add a public key

      pkcs15-init --store-public-key <keyfile> {-f <keyformat>} {-i <ID>}
                  {-l <label>}

Add data

      pkcs15-init -W <datafile> {-i <ID>} {-l <label>}

4. Other tools

SSL-engines

These libraries can be loaded in OpenSSL so you can do a certificate request with the openssl tool; the signature of the certificate request will then be made using the smart card. The result can then be sent to a CA for certification or the resulting certificate can be put on the card with pkcs15-init or pkcs11-tool.

pkcs11-tool and Mozilla/Netscape

You can use the OpenSC pkcs11 library to generate a key pair in Mozilla or Netscape, and let the browser generate a certificate request that is sent to an on-line CA to issue and send you a certificate that is then added to the card.

Just go to an online CA (Globalsign, Thawte, ...) and follow their guidelines. Because such a request either costs you or at least requires you to provide a valid mail address, it is advisable to first try you card with "pkcs11-tool --moz-cert <cert_file_in_der_format> --login".

NOTE: This can only be done with the onepin profile option (because the browser won't ask for an SO PIN, only for the user PIN).

5. Card-specific issues

Experience is that marvelous thing that enables you to recognize a mistake when you make it again. -- Franklin P. Jones

Cryptoflex:

Starcos SPK 2.3: