edent
125 lines
4.2 KiB
Plaintext
125 lines
4.2 KiB
Plaintext
== 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
|