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.
The complete specifications are available at https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html.
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
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
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.
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);
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;
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).
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:
The default user PIN for the YubiKey is
The default management key is
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
should be used for such operations. This is also supported and might
become the only available mechanism in the future.
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.
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