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;

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: