Merge branch 'development' into githubmaster
Added new material for yubico-piv-tool and ykcs11.
This commit is contained in:
Alessio Di Mauro
@@ -1,8 +1,8 @@
|
||||
Certificate Authority with NEO
|
||||
Certificate Authority with
|
||||
------------------------------
|
||||
|
||||
This document explains how to set up a Certificate Authority (CA) with
|
||||
Sub-CA private keys stored on YubiKey NEOs. Typical use for this is
|
||||
Sub-CA private keys stored on YubiKeys. Typical use for this is
|
||||
to generate HTTPS certificates for internal servers.
|
||||
|
||||
Considerations
|
||||
@@ -10,12 +10,12 @@ Considerations
|
||||
|
||||
For our example, we have chosen to use one root CA with a private key
|
||||
stored in an offline machine, that signs sub-CAs with private keys
|
||||
stored on YubiKey NEOs, which signs end-entity (EE) certs. We'll
|
||||
stored on YubiKeys, which signs end-entity (EE) certs. We'll
|
||||
generate the Sub-CA private keys on an offline host and save a copy of
|
||||
those keys.
|
||||
|
||||
We have chosen to use a RSA 3744 bit root CA key, and RSA 2048 bit
|
||||
keys for the NEO Sub-CAs and EE certificates. The NEO is limited to
|
||||
keys for the Sub-CAs and EE certificates. The is limited to
|
||||
RSA 1k and 2k keys (it supports ECDSA too but we chose to not use that
|
||||
here).
|
||||
|
||||
@@ -39,7 +39,7 @@ offline machine, booted from a LiveCD. Some additional packages may
|
||||
be required (pcscd, etc, see below) and will have to be transferred on
|
||||
a USB stick.
|
||||
|
||||
You need a YubiKey NEO with the PIV applet on, which you can purchase
|
||||
You need a YubiKey with the PIV application on, which you can purchase
|
||||
from Yubico.
|
||||
|
||||
You need to install the PKCS#11 Engine:
|
||||
@@ -89,15 +89,15 @@ You may inspect the newly generated root CA with:
|
||||
|
||||
openssl x509 -text < yubico-internal-https-ca-crt.pem
|
||||
|
||||
Preparing a Sub-CA NEO
|
||||
Preparing a Sub-CA
|
||||
----------------------
|
||||
|
||||
We need to change the management key, PIN and PUK code following the
|
||||
YubiKey-NEO-PIV-Introduction.txt document. We also want to save a
|
||||
YubiKey-PIV-Introduction.txt document. We also want to save a
|
||||
copy of these values. Here are the steps that are needed to be done
|
||||
for each new Sub-CA NEO.
|
||||
for each new Sub-CA.
|
||||
|
||||
This step is parametrized with the name of the YubiKey NEO user.
|
||||
This step is parametrized with the name of the YubiKey user.
|
||||
Generate new management code, PIN and PUK as follows:
|
||||
|
||||
user=Simon
|
||||
@@ -108,7 +108,7 @@ Generate new management code, PIN and PUK as follows:
|
||||
puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
|
||||
echo $puk > yubico-internal-https-$user-puk.txt
|
||||
|
||||
Configure a fresh NEO with these parameters as follows:
|
||||
Configure a fresh with these parameters as follows:
|
||||
|
||||
yubico-piv-tool -a set-mgm-key -n $key
|
||||
yubico-piv-tool -k $key -a change-pin -P 123456 -N $pin
|
||||
@@ -117,7 +117,7 @@ Configure a fresh NEO with these parameters as follows:
|
||||
Creating a Sub-CA
|
||||
-----------------
|
||||
|
||||
This step is parametrized with the name of the YubiKey NEO user. This
|
||||
This step is parametrized with the name of the YubiKey user. This
|
||||
means we will have one Sub-CA for every person authorized to sign
|
||||
certificates in our CA.
|
||||
|
||||
@@ -157,11 +157,11 @@ You may inspect the newly generated EE cert with this command:
|
||||
|
||||
openssl x509 -text < yubico-internal-https-subca-$user-crt.pem
|
||||
|
||||
Import Sub-CA key to NEO:
|
||||
Import Sub-CA key to:
|
||||
|
||||
yubico-piv-tool -k $key -a import-key -s 9c < yubico-internal-https-subca-$user-key.pem
|
||||
|
||||
Import Sub-CA cert to NEO:
|
||||
Import Sub-CA cert to:
|
||||
|
||||
yubico-piv-tool -k $key -a import-certificate -s 9c < yubico-internal-https-subca-$user-crt.pem
|
||||
|
||||
@@ -190,7 +190,7 @@ Then generate a new private key and certificate request:
|
||||
EOF
|
||||
openssl req -sha256 -new -config yubico-internal-https-ee-$host-csr.conf -key yubico-internal-https-ee-$host-key.pem -nodes -out yubico-internal-https-ee-$host-csr.pem
|
||||
|
||||
Then sign the certificate using the NEO:
|
||||
Then sign the certificate using the:
|
||||
|
||||
cat>yubico-internal-https-ee-$host-crt.conf<<EOF
|
||||
basicConstraints = critical,CA:false
|
||||
@@ -1,14 +1,14 @@
|
||||
Request, load and use OS X code signing certificates
|
||||
---------------------------------------------------
|
||||
|
||||
This is a short step-by-step on how to generate a key in the Neo,
|
||||
This is a short step-by-step on how to generate a key in the,
|
||||
create a certificate request, submit that request to apple, load the
|
||||
certificate in the Neo and use it for code signing.
|
||||
certificate in the and use it for code signing.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey Neo with the PIV applet loaded
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* the OpenSC software
|
||||
* membership in the mac developer program
|
||||
@@ -45,11 +45,11 @@ Steps
|
||||
+
|
||||
NOTE: -K DER is available from version 0.1.3, with earlier convert to PEM and import.
|
||||
|
||||
8. Set a new chuid in the applet to make sure nothing is cached for the key:
|
||||
8. Set a new chuid in the application to make sure nothing is cached for the key:
|
||||
|
||||
$ yubico-piv-tool -a set-chuid
|
||||
|
||||
9. Re-plug the Neo and make sure the certificates show up under the keychain
|
||||
9. Re-plug the and make sure the certificates show up under the keychain
|
||||
"PIV_II" in Keychain Access.
|
||||
|
||||
10. Use the certificates as usual with codesign/pkgbuild/productbuild/productsign
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
Using PIV for SSH through PKCS11
|
||||
--------------------------------
|
||||
|
||||
This is a step-by-step for how to get a Neo with PIV to work for
|
||||
This is a step-by-step for how to get a with PIV to work for
|
||||
public-key authentication with OpenSSH through PKCS11.
|
||||
Primarily on a OS X or Linux system.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey Neo with the PIV applet loaded
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* the OpenSC software
|
||||
* OpenSSH
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
Request and load a certificate from Windows CA
|
||||
----------------------------------------------
|
||||
|
||||
This is a short step-by-step on how to generate a key in the Neo,
|
||||
This is a short step-by-step on how to generate a key in the,
|
||||
create a certificate request, submit that request to a Windows CA
|
||||
and then load the certificate in the Neo.
|
||||
and then load the certificate in the.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey Neo with the PIV applet loaded
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* credentials to request certs from a Windows CA
|
||||
|
||||
@@ -29,7 +29,7 @@ Steps
|
||||
|
||||
certreq -submit -attrib "CertificateTemplate:User" request.csr cert.crt
|
||||
|
||||
4. Load the certificate in the Neo:
|
||||
4. Load the certificate in the:
|
||||
|
||||
yubico-piv-tool -s 9a -a import-certificate -i cert.crt
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -1,7 +1,7 @@
|
||||
Introduction to the YubiKey NEO PIV Applet
|
||||
==========================================
|
||||
Introduction to the YubiKey PIV Application
|
||||
===============================================
|
||||
|
||||
The YubiKey NEO supports the Personal Identity Verification (PIV) card
|
||||
The YubiKey supports the Personal Identity Verification (PIV) card
|
||||
interface specified in NIST SP 800-73 document "Cryptographic
|
||||
Algorithms and Key Sizes for PIV". This enables you to perform RSA or
|
||||
ECC sign/decrypt operations using a private key stored on the
|
||||
@@ -29,11 +29,11 @@ The maximum size of stored objects is 2005 bytes.
|
||||
Currently all functionality are available over both contact and
|
||||
contactless interfaces (contrary to what the specifications mandate).
|
||||
|
||||
Preparing a NEO for real use
|
||||
Preparing a for real use
|
||||
----------------------------
|
||||
|
||||
You would typically change the management key to make sure nobody but
|
||||
you can modify the state of the PIV applet on the NEO. Make sure to
|
||||
you can modify the state of the PIV application on the. Make sure to
|
||||
keep a copy of the key around for later use.
|
||||
|
||||
key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
|
||||
@@ -63,7 +63,7 @@ To reset PIN/PUK retry counter AND codes (default pin 123456 puk
|
||||
|
||||
yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
|
||||
|
||||
To reset the applet (PIN/PUK need to be blocked hence trying a couple
|
||||
To reset the application (PIN/PUK need to be blocked hence trying a couple
|
||||
of times -- you need to modify this if you have changed the default
|
||||
number of PIN/PUK retries).
|
||||
|
||||
@@ -94,7 +94,7 @@ middleware.
|
||||
Card Holder Unique Identifier
|
||||
-----------------------------
|
||||
|
||||
For the applet to be usable in windows the object CHUID (Card Holder
|
||||
For the application to be usable in windows the object CHUID (Card Holder
|
||||
Unique Identifier) has to be set and unique. The card contents are
|
||||
also aggressively cached so the CHUID has to be changed if the card
|
||||
contents change.
|
||||
Reference in New Issue
Block a user