YKCS11: added release notes.
This commit is contained in:
Alessio Di Mauro
@@ -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.
|
||||
Reference in New Issue
Block a user