# PKCS11 Module

PKCS #11: Cryptographic Token Interface Standard OpenSC implements v2.11 of the standard.

General

This standard specifies an API, called Cryptoki, to devices which hold cryptographic information and perform cryptographic functions. Cryptoki, pronounced crypto-key and short for cryptographic token interface, follows a simple object-based approach, addressing the goals of technology independence (any kind of device) and resource sharing (multiple applications accessing multiple devices), presenting to applications a common, logical view of the device called a cryptographic token.

OpenSC implements this standard in "opensc-pkcs11.so" module (on Windows: opensc-pkcs11.dll). Every Software that can use cryptographic tokens such as Mozilla, Firefox and Thunderbird can simply load this module and use all smart card supported by OpenSC for authentication, signing and decryption.

Virtual slots

Smart cards can have several pins, and make the keys available to only some of those. PKCS#11 interface however does not know about several pins. What OpenSC does is a trick: if you have more than one pin, you will see several card / slot, each with the name of that pin holder, and with the certificates/keys that pin can access. This feature is called virtual_slots and can be configured in the config file.

Example: Take a card with 2 PINs. Each PIN protects a private key and each private key has a corresponding cert chain. And then there are 3 other roots certs that have nothing to do with the other data. Now if num_slots = 4, hide_empty_tokens = false; and if you put the card your second card reader, you'll get the following:

- token in slot 4: PIN 1, key 1, cert chain 1
- token in slot 5: PIN 2, key 2, cert chain 2
- token in slot 6: the 3 other root certs
- token in slot 7: no data

If hide_empty_tokens would have been true, slot 7 wouldn't show a token.

Note: if in the example the 2 cert chain would have common certificates, those certificates would appear in the tokens in slots 4 and 5. (Which would cause a problem if those certs were deleted, this hasn't been solved yet in OpenSC).

Another good-to-know: the number of virtual slots has been hard-coded (it is 8 at the moment). So if num_slots = 4, only the first 2 readers will be visible. Or if you'd put num_slots to 3, the first 2 readers will have 3 virtual slots and the third reader will have 2.

Installation

In OpenSC up to 0.9.6 the module was installed in /usr/lib/pkcs11 on linux, also some libraries used by that module, and this cause some problems. The easiest way to fix it is to copy or symlink all files to /usr/lib.

OpenSC starting with 0.10.0 does it right and installs all libraries and the opensc-pkcs11.so plugin in /usr/lib.

Visibility of private keys

The PKCS11 standard requires that you provide a PIN before you can see info about the private keys that are protected by the PIN. This isn't realy needed for the OpenSC library (not sensitive things in the private key info) but a standard is a standard... It's also a problem if you want to see if there are keys on the cards without providing a PIN first. There's no real solution to this; perhaps the best way is to enumerate the certs, and assume that each non-CA cert has a corresponding private key on the card (this requires to parse the certs, you can't get this info from PKCS11).