1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
|
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
http://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
----
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 disabled. This is _highly_ verbose
and might be confusing. In order to enabled it rebuild the project as
follows:
----
yubico-piv-tool$ autoreconf --install
yubico-piv-tool$ ./configure --enable-ykcs11-debug
yubico-piv-tool$ make
yubico-piv-tool$ sudo make install
----
|