A newer version of this documentation is available.

View Latest

PKCS#11

Standard

The standard cryptographic application program interface PKCS#11 is available through the library:

Windows

iidp11.dll

Linux

libiidp11.so

MacOSX

libiidp11.dylib

See the Files section on the respective installation page for Windows, Linux, and macOS for the location of the installed files.

More information about the standard can be obtained from http://www.rsa.com/rsalabs/node.asp?id=2133.

This library allows the software to cooperate with applications supporting this interface, for example Mozilla Firefox web browser and Thunderbird mail client.

Version

The current version of the standard is 2.20, but our implementation will return 2.11 as version information. The difference between the two versions is algorithm extensions not concerning smart cards and changed suggestion for handling multiple PINs (see below). The suggestion regarding multiple PINs is useless and will be removed in future versions of the standard. The implementation in Net iD Enterprise will be upgraded when version 2.30 is released.

Applications implementing the standard should only be concerned with the major version (2) and minor versions adding support for specific algorithms which are needed, i.e. in those rare cases where a new specific algorithm is mandatory.

Third-party package

The PKCS#11 library may be installed in any location; it has no other binary dependencies, and only needs the configuration file for license information. For library version 5.4 and later the configuration file may be included in the binary, there is no need for a separate file.

Extended Functionality

Multiple PINs

A PKCS#11 slot may contain a PKCS#11 token. A PKCS#11 token is either a file or a smart card containing certificates, private keys and data objects.

A PKCS#11 token can only contain a single user PIN. There have been different approaches to handle the multiple PIN scenarios and our implementation has chosen the approach specified in PKCS#11 2.11 Appendix A.

For example when using a smart card ‘eID Card’ with two PINs: identification and signature in smart card reader Card Reader the PKCS#11 library will return two slots with token present:

  • 1 ‘Card Reader’ ‘eID Card (identification)’

  • 2 ‘Card Reader’ ‘eID Card (signature)’

The slots will have unique slot id, but identical slot description. The token label will be built from the token label and pin label. The format for building the combined token label:

  • "<real token label> (<pin label>)"

The reason for this approach is that from an application perspective everything works perfectly with the standard, no special implementation is needed for multiple PINs scenarios.

Unlock PIN

PIN unlocking is not part of PKCS#11, so the following function is added to support this feature commonly used with smart cards.

CK_RV CK_CALL_SPEC C_UnlockPIN(
    CK_SESSION_HANDLE hSession,
    CK_UTF8CHAR_PTR pPuk,
    CK_ULONG ulPukLen,
    CK_UTF8CHAR_PTR pPin,
    CK_ULONG ulPinLen)

The usage is equal to standard function C_SetPIN, but PUK will be sent instead of old PIN.

Common implementation mistakes

Unfortunately there are some common mistakes when implementing the PKCS#11 standard.

Never assume a single slot/token

As mentioned earlier a slot is something that may contain a token. A slot may be a smart card reader, a file or a hardware board, the standard sets no limitations. A token is something that may be present in a slot, but even here the standard sets no limitations.

Always ask the PKCS#11 library about all available slots, this will handle scenarios with multiple smart card readers and smart cards with multiple PINs.

Never work with private keys

A lot of people when first using the standard assume they should be concerned with the private keys. Only applications managing the private keys and certificates need to be concerned with the private key, all other applications should be using the certificate.

There are two reasons for handling certificates instead of private keys, there may be several certificates for a single private key and the certificate is usually public readable.

Multiple certificates for a single private key, also known as secondary or role certificates are commonly used with smart cards in Europe.

The second reason, public readable certificates, is a matter of usage, no need to logon the smart card until the private key should be used. Consider a scenario with multiple smart cards and/or multiple PINs. Using the private key will result in a lot of logon dialogs only to search for all available certificates/private keys.

Correct usage:

  1. Search all slots for all available certificates.

  2. Let user select certificate (automatic select if only a single certificate is available).

  3. Logon the token (if needed). Use token label as description for user to enter correct PIN.

  4. Find private key object, will have same CKA_ID as the certificate object.

  5. Use the private key.

There are some PKCS#11 implementations where certificates are not public readable, usually old smart cards with a single PIN from North America. As soon as multiple PINs are introduced, public readable certificates are usually considered the only way forward.

Examples

See https://service.secmaker.com/examples/pkcs11.aspx for examples using PKCS#11.