YKCS11

This is a PKCS#11 module that allows to communicate with the PIV application running on a YubiKey.

This module is based on version 2.40 of the PKCS#11 (Cryptoki) specifications.

BUILDING

YKCS11 is automatically built as part of yubico-piv-tool and the following command will suffice:

autoreconf --install
./configure
make
sudo make install

More info about building yubico-piv-tool can be found in the related README file or over at https://developers.yubico.com/yubico-piv-tool/.

Once installed, the module will be found by default in /usr/local/lib/libykcs11.so otherwise it will be built locally in yubico-piv-tool/ykcs11/.libs/libykcs11.so

PORTABILITY

The module has been developed and tested using Debian GNU/Linux and Ubuntu Linux. It is however possible to cross-compile it for Windows and Mac OS X using the relative makefiles (windows.mk and mac.mk). Both use PCSC as a backend.

Keep in mind that communication with the YubiKey is carried out over the CCID transport. Hence, on Mac OS X the YubiKey should be whitelisted (more info at https://github.com/Yubico/ifd-yubico).

Further testing at this stage has not been carried out, so additional tweaks might be needed to use operating systems different from Linux.

SUPPORTED FUNCTIONALITY AND KNOWN ISSUES

YKCS11 is not a full implementation of PKCS#11. Some functionality are not present and others are not yet implemented.

In its current form YKCS11 implements a smaller subset of functionality:

  • RSA key generation
    1024 or 2048 bit keys can be generated;

  • EC key generation
    curve prime256v1 is supported (256 bit keys);

  • RSA signature
    supported mechanisms are RSA-X-509 (raw RSA), PKCS1 (unhashed), PKCS1 with SHA1/256/384/512 and PSS with SHA1/256/384/512. The latter is implemented but has not been tested, hence is provided as is;

  • ECDSA signature
    supported mechanism are ECDSA (raw) and ECDSA with SHA1;

  • RSA and EC public key (X.509 certificate) import;

  • RSA and EC private key import
    with possibility of setting individual PIN policies and touch to sign (where supported);

  • Public key deletion.

PKCS#11 defines two types of users: a regular user and a security officer (SO). These have been mapped to perform regular usage of the private key material (PIN-associated operations) and device management (management-key associated operations).

Key Mapping

The module provides four main keys that can be used. These correspond to the four main keys in PIV and accessible through yubico-piv-tool. The mapping is as follows:

ykcs11 id PIV

0

9a

1

9e

2

9c

3

9d

PINs and Management Key

The default user PIN for the YubiKey is 123456.
The default management key is 010203040506070801020304050607080102030405060708.
All the YubiKey personalization (e.g. changing PIN, changing management key, resetting PINs, resetting the application) is currently done using yubico-piv-tool.

In order to perform operations involving the private keys, a regular user must be logged in (i.e. using the PIN). However, given the different PIN policies for different keys, subsequent operations might require a new login. Currently this is supported by the module allowing multiple Login operations with the appropriate user. According to PKCS#11 however, a special user called CONTEXT_SPECIFIC should be used for such operations. This is also supported and might become the only available mechanism in the future.

Key Generation

Key pair generation is a particular operation, in the sense that within PIV this is the only moment where the newly created public key is given back to the user. To prevent the key from being lost it is automatically stored within the YubiKey by wrapping it in an X.509 certificate. This certificate is however empty. It does not have other valid information except for the public key.

DEBUGGING

By default the module has debugging disabled. This is highly verbose and might be confusing. In order to enabled it rebuild the project as follows:

autoreconf --install
./configure --enable-ykcs11-debug
make
sudo make install