From a8825c99f32860120af9e2d8a6f8100e8fefb974 Mon Sep 17 00:00:00 2001 From: Alessio Di Mauro Date: Fri, 6 Nov 2015 13:58:46 +0100 Subject: [PATCH] YKCS11: added release notes. --- doc/YKCS11_release_notes.adoc | 132 ++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 doc/YKCS11_release_notes.adoc diff --git a/doc/YKCS11_release_notes.adoc b/doc/YKCS11_release_notes.adoc new file mode 100644 index 0000000..e53609d --- /dev/null +++ b/doc/YKCS11_release_notes.adoc @@ -0,0 +1,132 @@ +YKCS11 +------ + +This is a PKCS#11 module that allows to communicate with the PIV +application running on a YubiKey. + +BUILDING +~~~~~~~~ + +YKCS11 is automatically built as part of `yubico-piv-tool` and the +following command will suffice + +---- +yubico-piv-tool$ autoreconf --install +yubico-piv-tool$ ./configure +yubico-piv-tool$ make +yubico-piv-tool$ 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 enabled. This is _highly_ verbose +and might be confusing. In order to disable it, the two macros +`YKCS11_DBG` and `YKCS11_DINOUT` in the file `debug.h` should be set +to `0`. Once this is done the module must be recompiled.