== 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.

The complete specifications are available at
https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html.

=== 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:

[cols="2*^", options="header"]
|===
|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