Updated docs.
This commit is contained in:
Dain Nilsson
@@ -1,9 +1,6 @@
|
||||
Yubico PIV Tool
|
||||
===============
|
||||
|
||||
Introduction
|
||||
------------
|
||||
== Yubico PIV Tool
|
||||
|
||||
=== Introduction
|
||||
The Yubico PIV tool is used for interacting with the Privilege and
|
||||
Identification Card (PIV) application on a https://www.yubico.com[YubiKey].
|
||||
|
||||
@@ -11,9 +8,11 @@ With it you may generate keys on the device, importing keys and
|
||||
certificates, and create certificate requests, and other operations.
|
||||
A shared library and a command-line tool is included.
|
||||
|
||||
License
|
||||
-------
|
||||
==== Usage guides
|
||||
For information and examples on what you can do with a PIV enabled YubiKey,
|
||||
see https://developers.yubico.com/PIV/
|
||||
|
||||
=== License
|
||||
In general the project is covered by the following BSD license. The
|
||||
file ykcs11/pkcs11.h has additional copyright and licensing
|
||||
information, please see it for more information. Some other files
|
||||
@@ -49,15 +48,13 @@ infrastructure.
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
----
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
=== Building
|
||||
After downloading and unpacking the package tarball, you build it as
|
||||
follows.
|
||||
|
||||
./configure
|
||||
make
|
||||
sudo make install
|
||||
$ ./configure
|
||||
$ make
|
||||
$ sudo make install
|
||||
|
||||
The backend to use is decided at compile time, see the summary at the
|
||||
end of the ./configure output. Use --with-backend=foo to chose
|
||||
@@ -69,80 +66,74 @@ under Mac OS X, and "winscard" is used under Windows. In most
|
||||
situations, running ./configure should automatically find the proper
|
||||
backend to use.
|
||||
|
||||
Building from Git
|
||||
-----------------
|
||||
|
||||
=== Building from Git
|
||||
Recent versions of autoconf, automake, pkg-config and libtool must
|
||||
be installed. Help2man is used to generate the manpages. Gengetopt
|
||||
version 2.22.6 or later is needed for command line parameter handling.
|
||||
|
||||
Generate the build system using:
|
||||
|
||||
autoreconf --install
|
||||
$ autoreconf --install
|
||||
|
||||
Then you follow the normal build instructions, see above.
|
||||
To turn on all warnings add --enable-gcc-warnings to ./configure
|
||||
|
||||
Portability
|
||||
-----------
|
||||
|
||||
=== Portability
|
||||
The main development platform is Debian GNU/Linux. The project is
|
||||
cross-compiled to Windows using MinGW (see windows.mk) using the PCSC
|
||||
backend. It may also be built for Mac OS X (see mac.mk), also using
|
||||
the PCSC backend.
|
||||
|
||||
Example Usage
|
||||
-------------
|
||||
|
||||
=== Example Usage
|
||||
For a list of all available options --help can be given. For more information
|
||||
on exactly what happens --verbose or --verbose=2 may be added.
|
||||
|
||||
Generate a new ECC-P256 key on device in slot 9a, will print the public
|
||||
key on stdout:
|
||||
|
||||
yubico-piv-tool -s 9a -A ECCP256 -a generate
|
||||
$ yubico-piv-tool -s 9a -A ECCP256 -a generate
|
||||
|
||||
Generate a certificate request with public key from stdin, will print
|
||||
the resulting request on stdout:
|
||||
|
||||
yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
|
||||
$ yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
|
||||
-a verify -a request
|
||||
|
||||
Generate a self-signed certificate with public key from stdin, will print
|
||||
the certificate, for later import, on stdout:
|
||||
|
||||
yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
|
||||
$ yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
|
||||
-a verify -a selfsign
|
||||
|
||||
Import a certificate from stdin:
|
||||
|
||||
yubico-piv-tool -s 9a -a import-certificate
|
||||
$ yubico-piv-tool -s 9a -a import-certificate
|
||||
|
||||
Set a random chuid, import a key and import a certificate from a PKCS12
|
||||
file with password test, into slot 9c:
|
||||
|
||||
yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
|
||||
$ yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
|
||||
-a import-key -a import-cert
|
||||
|
||||
Change the management key used for administrative authentication:
|
||||
|
||||
yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
|
||||
$ yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
|
||||
-a set-mgm-key
|
||||
|
||||
Delete a certificate in slot 9a:
|
||||
|
||||
yubico-piv-tool -a delete-certificate -s 9a
|
||||
$ yubico-piv-tool -a delete-certificate -s 9a
|
||||
|
||||
Show some information on certificates and other data:
|
||||
|
||||
yubico-piv-tool -a status
|
||||
$ yubico-piv-tool -a status
|
||||
|
||||
Read out the certificate from a slot and then run a signature test:
|
||||
|
||||
yubico-piv-tool -a read-cert -s 9a
|
||||
yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
|
||||
$ yubico-piv-tool -a read-cert -s 9a
|
||||
$ yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
|
||||
|
||||
Import a key into slot 85 (only available on YubiKey 4) and set the
|
||||
touch policy (also only available on YubiKey 4):
|
||||
|
||||
yubico-piv-tool -a import-key -s 85 --touch-policy=always -i key.pem
|
||||
$ yubico-piv-tool -a import-key -s 85 --touch-policy=always -i key.pem
|
||||
|
||||
@@ -1,73 +0,0 @@
|
||||
Load and use Android code signing certificate
|
||||
---------------------------------------------
|
||||
|
||||
This is a step-by-step guide on how to load and use an android code signing
|
||||
key and certificate.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey with the PIV application
|
||||
* the yubico-piv-tool software
|
||||
* the OpenSC software
|
||||
* jarsigner and keytool from the JDK (OpenJDK 8 used here)
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Import the key and cert, do one of the below:
|
||||
a. Import the key and cert (PEM format) in slot 9a:
|
||||
+
|
||||
----
|
||||
$ yubico-piv-tool -s 9a -a import-key -i key.pem
|
||||
$ yubico-piv-tool -s 9a -a import-certificate -i cert.pem
|
||||
----
|
||||
|
||||
b. Import the key and cert (PKCS12 format) in slot 9a:
|
||||
+
|
||||
----
|
||||
$ yubico-piv-tool -s 9a -a import-key -a import-cert -i key.p12 -K PKCS12
|
||||
----
|
||||
|
||||
2. Create a java pkcs11 configuration file:
|
||||
+
|
||||
----
|
||||
cat > /tmp/pkcs11_java.cfg
|
||||
name = OpenSC-PKCS11
|
||||
description = SunPKCS11 via OpenSC
|
||||
library = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
|
||||
slotListIndex = 1
|
||||
----
|
||||
|
||||
3. Check that keytool can see the key:
|
||||
+
|
||||
----
|
||||
$ keytool -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /tmp/pkcs11_java.cfg \
|
||||
-keystore NONE -storetype PKCS11 -list
|
||||
Enter keystore password:
|
||||
|
||||
Keystore type: PKCS11
|
||||
Keystore provider: SunPKCS11-OpenSC-PKCS11
|
||||
|
||||
Your keystore contains 1 entry
|
||||
|
||||
Certificate for PIV Authentication, PrivateKeyEntry,
|
||||
Certificate fingerprint (SHA1): 26:D7:CB:71:6D:42:3C:AB:58:69:E0:9D:F0:16:DF:84:7E:1C:5A:9A
|
||||
----
|
||||
+
|
||||
Password here is the PIN of the key (default 123456).
|
||||
|
||||
4. Sign the apk with jarsigner:
|
||||
+
|
||||
----
|
||||
$ jarsigner -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /tmp/pkcs11_java.cfg \
|
||||
-keystore NONE -storetype PKCS11 app.apk "Certificate for PIV Authentication"
|
||||
Enter Passphrase for keystore:
|
||||
jar signed.
|
||||
----
|
||||
|
||||
5. Verify the signature with jarsigner:
|
||||
+
|
||||
----
|
||||
$ jarsigner -verify app.apk
|
||||
----
|
||||
@@ -1,13 +1,12 @@
|
||||
Using Attestation
|
||||
-----------------
|
||||
== Using Attestation
|
||||
|
||||
== Introduction
|
||||
=== Introduction
|
||||
This feature is only available in YubiKey 4.3 and newer.
|
||||
|
||||
A high level description of the thinking and how this can be used can be found
|
||||
at https://developers.yubico.com/PIV/Introduction/PIV_attestation.html
|
||||
|
||||
== Usage
|
||||
=== Usage
|
||||
Attestation works through a special key slot called “f9” this comes
|
||||
pre-loaded from factory with a key and cert signed by Yubico, but can be
|
||||
overwritten.
|
||||
@@ -20,7 +19,7 @@ special key, this can be realised by using the yubico-piv-tool action attest:
|
||||
|
||||
The output of this is a PEM encoded certificate, signed by the key in slot f9.
|
||||
|
||||
== Verifying
|
||||
=== Verifying
|
||||
To verify an attestation step 1 is to build the certificate chain. Put the
|
||||
attestation root certificate in a file (or if you trust several put all
|
||||
of them in said file). The Yubico root certificate can be found at
|
||||
|
||||
@@ -1,208 +0,0 @@
|
||||
Certificate Authority with a YubiKey
|
||||
------------------------------------
|
||||
|
||||
This document explains how to set up a Certificate Authority (CA) with
|
||||
Sub-CA private keys stored on YubiKeys. Typical use for this is
|
||||
to generate HTTPS certificates for internal servers.
|
||||
|
||||
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 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 Sub-CAs and EE certificates. The YubiKey is limited to
|
||||
RSA 1k and 2k keys (it supports ECDSA too but we chose to not use that
|
||||
here).
|
||||
|
||||
By setting some name constraints, we are trying to limit to powers of
|
||||
this CA. This is not fully supported by all environments, but it
|
||||
should do no harm, and may be useful in some environments.
|
||||
|
||||
The root also has a path length constraint of 1 to prevent the Sub-CAs
|
||||
from issuing further Sub-Sub-CAs.
|
||||
|
||||
We also set a expiry date far away in the future on the root CA
|
||||
(expiring in 1000000 days) and use datefudge to set an arbitrary start
|
||||
date for the CA, to avoid leaking the time of CA creation which would
|
||||
leak some bits if information going into the randomness generation.
|
||||
|
||||
Preparations
|
||||
------------
|
||||
|
||||
We use OpenSSL to generate keys and certificates. This is done on an
|
||||
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 with the PIV application on, which you can purchase
|
||||
from Yubico.
|
||||
|
||||
You need to install the PKCS#11 Engine:
|
||||
|
||||
sudo dpkg -i libengine-pkcs11-openssl*
|
||||
|
||||
or if you are on a connected machine, more simpler:
|
||||
|
||||
sudo apt-get install libengine-pkcs11-openssl
|
||||
|
||||
Creating a Root CA
|
||||
-------------------
|
||||
|
||||
Generate the private key as follows:
|
||||
|
||||
openssl genrsa -out yubico-internal-https-ca-key.pem 3744
|
||||
|
||||
Generate the Root CA certificate and initialize the CA serial number
|
||||
counter as follows:
|
||||
|
||||
cat>yubico-internal-https-ca.conf<<EOF
|
||||
[ req ]
|
||||
x509_extensions = v3_ca
|
||||
distinguished_name = req_distinguished_name
|
||||
prompt = no
|
||||
[ req_distinguished_name ]
|
||||
CN=Yubico Internal HTTPS CA
|
||||
[ v3_ca ]
|
||||
subjectKeyIdentifier=hash
|
||||
basicConstraints=critical,CA:true,pathlen:1
|
||||
keyUsage=critical,keyCertSign,cRLSign
|
||||
nameConstraints=critical,@nc
|
||||
[ nc ]
|
||||
permitted;otherName=1.3.6.1.5.5.7.8.7;IA5:yubico.com
|
||||
permitted;email.0=yubico.com
|
||||
permitted;email.1=.yubico.com
|
||||
permitted;DNS=yubico.com
|
||||
permitted;URI.0=yubico.com
|
||||
permitted;URI.1=.yubico.com
|
||||
permitted;IP.0=0.0.0.0/255.255.255.255
|
||||
permitted;IP.1=::/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
|
||||
EOF
|
||||
datefudge "2014-01-01 UTC" openssl req -new -sha256 -x509 -set_serial 1 -days 1000000 -config yubico-internal-https-ca.conf -key yubico-internal-https-ca-key.pem -out yubico-internal-https-ca-crt.pem
|
||||
echo 01 > yubico-internal-https-ca-crt.srl
|
||||
|
||||
You may inspect the newly generated root CA with:
|
||||
|
||||
openssl x509 -text < yubico-internal-https-ca-crt.pem
|
||||
|
||||
Preparing a Sub-CA
|
||||
----------------------
|
||||
|
||||
We need to change the management key, PIN and PUK code following the
|
||||
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.
|
||||
|
||||
This step is parametrized with the name of the YubiKey user.
|
||||
Generate new management code, PIN and PUK as follows:
|
||||
|
||||
user=Simon
|
||||
key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
|
||||
echo $key > yubico-internal-https-$user-key.txt
|
||||
pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
|
||||
echo $pin > yubico-internal-https-$user-pin.txt
|
||||
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 YubiKey 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
|
||||
yubico-piv-tool -k $key -a change-puk -P 12345678 -N $puk
|
||||
|
||||
Creating a Sub-CA
|
||||
-----------------
|
||||
|
||||
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.
|
||||
|
||||
user=Simon
|
||||
|
||||
We first need to load the management key and PIN code from the
|
||||
previous section.
|
||||
|
||||
key=`cat yubico-internal-https-$user-key.txt`
|
||||
pin=`cat yubico-internal-https-$user-pin.txt`
|
||||
|
||||
Generate the private key:
|
||||
|
||||
openssl genrsa -out yubico-internal-https-subca-$user-key.pem 2048
|
||||
|
||||
Generate the Sub-CA certificate request:
|
||||
|
||||
cat>yubico-internal-https-subca-$user-csr.conf<<EOF
|
||||
[ req ]
|
||||
distinguished_name = req_distinguished_name
|
||||
prompt = no
|
||||
[ req_distinguished_name ]
|
||||
CN=Yubico Internal HTTPS $user Sub-CA
|
||||
EOF
|
||||
openssl req -sha256 -new -config yubico-internal-https-subca-$user-csr.conf -key yubico-internal-https-subca-$user-key.pem -nodes -out yubico-internal-https-subca-$user-csr.pem
|
||||
|
||||
Generate the Sub-CA certificate:
|
||||
|
||||
cat>yubico-internal-https-subca-$user-crt.conf<<EOF
|
||||
basicConstraints = critical, CA:true, pathlen:0
|
||||
keyUsage=critical, keyCertSign
|
||||
EOF
|
||||
openssl x509 -sha256 -CA yubico-internal-https-ca-crt.pem -CAkey yubico-internal-https-ca-key.pem -req -in yubico-internal-https-subca-$user-csr.pem -extfile yubico-internal-https-subca-$user-crt.conf -out yubico-internal-https-subca-$user-crt.pem
|
||||
echo 00 > yubico-internal-https-subca-$user-crt.srl
|
||||
|
||||
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 the YubiKey:
|
||||
|
||||
yubico-piv-tool -k $key -a import-key -s 9c < yubico-internal-https-subca-$user-key.pem
|
||||
|
||||
Import Sub-CA cert to the YubiKey:
|
||||
|
||||
yubico-piv-tool -k $key -a import-certificate -s 9c < yubico-internal-https-subca-$user-crt.pem
|
||||
|
||||
Creating End-Entity Certificates
|
||||
--------------------------------
|
||||
|
||||
This step is parametrized with the hostname, and the name of the
|
||||
Sub-CA used to sign the EE, so set it first:
|
||||
|
||||
host=munin
|
||||
user=Simon
|
||||
|
||||
We first need to load the PIN code from the previous section.
|
||||
|
||||
pin=`cat yubico-internal-https-$user-pin.txt`
|
||||
|
||||
Then generate a new private key and certificate request:
|
||||
|
||||
openssl genrsa -out yubico-internal-https-ee-$host-key.pem 2048
|
||||
cat>yubico-internal-https-ee-$host-csr.conf<<EOF
|
||||
[ req ]
|
||||
distinguished_name = req_distinguished_name
|
||||
prompt = no
|
||||
[ req_distinguished_name ]
|
||||
CN=$host.yubico.com
|
||||
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:
|
||||
|
||||
cat>yubico-internal-https-ee-$host-crt.conf<<EOF
|
||||
basicConstraints = critical,CA:false
|
||||
keyUsage=critical,digitalSignature,keyEncipherment
|
||||
extendedKeyUsage=critical,serverAuth
|
||||
subjectAltName=critical,DNS:$host.yubico.com
|
||||
EOF
|
||||
openssl << EOF
|
||||
engine dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so -pre ID:pkcs11 -pre NO_VCHECK:1 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -pre VERBOSE
|
||||
x509 -engine pkcs11 -CAkeyform engine -CAkey slot_1-id_2 -sha256 -CA yubico-internal-https-subca-$user-crt.pem -req -passin pass:$pin -in yubico-internal-https-ee-$host-csr.pem -extfile yubico-internal-https-ee-$host-crt.conf -out yubico-internal-https-ee-$host-crt.pem
|
||||
EOF
|
||||
|
||||
You may inspect the newly generated EE cert with this command:
|
||||
|
||||
openssl x509 -text < yubico-internal-https-ee-$host-crt.pem
|
||||
@@ -1,55 +0,0 @@
|
||||
Request, load and use OS X code signing certificates
|
||||
---------------------------------------------------
|
||||
|
||||
This is a short step-by-step on how to generate a key on a YubiKey,
|
||||
create a certificate request, submit that request to apple, load the
|
||||
certificate in the YubiKey and use it for code signing.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* the OpenSC software
|
||||
* membership in the mac developer program
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Generate a key in slot 9a:
|
||||
|
||||
$ yubico-piv-tool -s 9a -a generate -o public.pem
|
||||
|
||||
2. Create a certificate request for app distribution:
|
||||
|
||||
$ yubico-piv-tool -a verify-pin -P 123456 -s 9a -a request-certificate \
|
||||
-S "/CN=Application/" -i public.pem -o application.csr
|
||||
|
||||
3. Generate a key in slot 9c:
|
||||
|
||||
$ yubico-piv-tool -s 9c -a generate -o public.pem
|
||||
|
||||
4. Create a certificate request for installer distribution:
|
||||
|
||||
$ yubico-piv-tool -a verify-pin -P 123456 -s 9c -a request-certificate \
|
||||
-S "/CN=Installer/" -i public.pem -o installer.csr
|
||||
|
||||
5. Go to the Apple developer program page and submit the requests.
|
||||
|
||||
6. When the certificates are ready and approved, download them.
|
||||
|
||||
7. Load the certificates:
|
||||
|
||||
$ yubico-piv-tool -a import-certificate -s 9a -K DER -i mac_app.cer
|
||||
$ yubico-piv-tool -a import-certificate -s 9c -K DER -i mac_installer.cer
|
||||
+
|
||||
NOTE: -K DER is available from version 0.1.3, with earlier convert to PEM and import.
|
||||
|
||||
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 YubiKey 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,76 +0,0 @@
|
||||
Using SSH User Certificates with PIV keys
|
||||
-----------------------------------------
|
||||
|
||||
This is a step-by-step on how to setup SSH user certificates using PIV
|
||||
for hardware-backed keys. This guide is primarily for an OS X or
|
||||
Linux system.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* the ykcs11 PKCS#11 module
|
||||
* OpenSSH
|
||||
|
||||
[NOTE]
|
||||
This has been tested as working with OpenSSH version 7.2p2.
|
||||
It has also been tested as *not working* with OpenSSH version 6.9p1.
|
||||
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Generate an "ssh user CA" key and trust it for this account on this
|
||||
host
|
||||
|
||||
$ ssh-keygen -N '' -C user-ca -f ~/.ssh/ca
|
||||
$ sed 's/^/cert-authority /' ~/.ssh/ca.pub > ~/.ssh/authorized_keys
|
||||
|
||||
2. Generate a key in PIV slot 9c that requires touch. (Note the second
|
||||
operation will require touch)
|
||||
|
||||
$ yubico-piv-tool -a generate -s 9c -A RSA2048 --pin-policy=never --touch-policy=always -o public.pem
|
||||
$ yubico-piv-tool -a selfsign-certificate -s 9c -S "/CN=SSH key/" -i public.pem -o cert.pem
|
||||
$ yubico-piv-tool -a import-certificate -s 9c -i cert.pem
|
||||
|
||||
3. Double check that the key appears in slot 9c (optional)
|
||||
|
||||
$ yubico-piv-tool -a status
|
||||
|
||||
4. Clear the SSH agent
|
||||
|
||||
$ ssh-add -D
|
||||
$ ssh-add -e /PATH/TO/libykcs11.so
|
||||
|
||||
* Make sure to use the correct path (e.g. `/usr/local/lib`) and extension (`.so` for Linux, `.dylib` for Mac OS X) for libykcs11.
|
||||
|
||||
* Beware that `ssh-add -D` doesn't seem to clear PKCS#11 libraries, only keys
|
||||
(http://lists.mindrot.org/pipermail/openssh-unix-dev/2016-July/035154.html[link]).
|
||||
|
||||
5. Add PIV to the SSH agent (will prompt for PIV PIN)
|
||||
|
||||
$ ssh-add -s /PATH/TO/libykcs11.so
|
||||
|
||||
6. Get the public key from PIV and sign it using the CA key. This produces `~/.ssh/id_rsa-cert.pub`
|
||||
|
||||
$ ssh-add -L > ~/.ssh/id_rsa.pub
|
||||
$ ssh-keygen -s ~/.ssh/ca -I identity -n "${LOGNAME}" ~/.ssh/id_rsa.pub
|
||||
|
||||
7. Authenticate to the target system using the new key:
|
||||
|
||||
$ ssh user@remote.example.com
|
||||
|
||||
If you have followed these steps to the letter, you will not be asked for the PIV PIN, but your YubiKey will start blinking, waiting for touch.
|
||||
|
||||
More info
|
||||
---------
|
||||
|
||||
For more information see the CERTIFICATES section of http://man.openbsd.org/OpenBSD-current/man1/ssh-keygen.1[ssh-keygen(1)].
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
Thanks to Christopher Harrell and Dean Sutherland from the
|
||||
https://yahoo-security.tumblr.com/[Yahoo Paranoids] for providing the
|
||||
instruction and the testing.
|
||||
@@ -1,72 +0,0 @@
|
||||
Using PIV for SSH through PKCS11
|
||||
--------------------------------
|
||||
|
||||
This is a step-by-step for how to get a YubiKey with PIV to work for
|
||||
public-key authentication with OpenSSH through PKCS11.
|
||||
Primarily on a OS X or Linux system.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* the OpenSC software
|
||||
* OpenSSH
|
||||
** If you are using OSX El Capitan (10.11) or earlier, for ssh-agent to work a newer OpenSSH than is delivered with the system; macOS Sierra (10.12) contains a compatible version
|
||||
|
||||
[NOTE]
|
||||
The following example assume that you have not yet changed the management key. If you have changed the management key, add `--key` to the `yubico-piv-tool -a import-certificate` command below.
|
||||
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Generate a key in slot 9a (any slot should suffice):
|
||||
|
||||
$ yubico-piv-tool -s 9a -a generate -o public.pem
|
||||
+
|
||||
[NOTE]
|
||||
RSA 4096-bit keys are not currently supported due to a limitation in the PIV spec: https://github.com/Yubico/yubico-piv-tool/issues/58
|
||||
|
||||
2. Create a self-signed certificate for that key.
|
||||
The only use for the X.509 certificate is to make PIV/PKCS#11 lib happy.
|
||||
They would want to be able to extract the public-key from the smartcard,
|
||||
and do that through the X.509 certificate.
|
||||
|
||||
$ yubico-piv-tool -a verify-pin -a selfsign-certificate -s 9a -S "/CN=SSH key/" -i public.pem -o cert.pem
|
||||
|
||||
3. Load the certificate:
|
||||
|
||||
$ yubico-piv-tool -a import-certificate -s 9a -i cert.pem
|
||||
|
||||
4. Find out where OpenSC has installed the pkcs11 module.
|
||||
|
||||
* For OS X with binary installation this is typically in `/Library/OpenSC/lib/`. Homebrew users can use `export OPENSC_LIBS=$(brew --prefix opensc)/lib`.
|
||||
|
||||
* For a Debian based system this is typically in `/usr/lib/x86_64-linux-gnu/`
|
||||
+
|
||||
After this we'll call this location `$OPENSC_LIBS`
|
||||
|
||||
5. Export the public key in correct format for ssh and once you got it,
|
||||
add it to authorized_keys on the target system.
|
||||
|
||||
$ ssh-keygen -D $OPENSC_LIBS/opensc-pkcs11.so -e
|
||||
+
|
||||
[NOTE]
|
||||
The command will export all keys stored on the YubiKey Neo.
|
||||
Hopefully it will keep the slot order so it should be not hard to guess which
|
||||
is the public key associated with your targeted private key.
|
||||
|
||||
6. Authenticate to the target system using the new key:
|
||||
|
||||
$ ssh -I $OPENSC_LIBS/opensc-pkcs11.so user@remote.example.com
|
||||
|
||||
7. This can also be setup to work with ssh-agent: (Optional)
|
||||
|
||||
$ ssh-add -s $OPENSC_LIBS/opensc-pkcs11.so
|
||||
+
|
||||
NOTE: On OS X prior to macOS 10.12 “Sierra” this typically requires installation of a third-party OpenSSH from Homebrew or the like and using that ssh-agent.
|
||||
+
|
||||
To confirm that the ssh-agent correctly finds that key and getting the public key in correct format:
|
||||
|
||||
$ ssh-add -L
|
||||
@@ -1,43 +0,0 @@
|
||||
Request and load a certificate from Windows CA
|
||||
----------------------------------------------
|
||||
|
||||
This is a short step-by-step on how to generate a key on a YubiKey,
|
||||
create a certificate request, submit that request to a Windows CA
|
||||
and then load the certificate on the YubiKey.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* a YubiKey with the PIV application loaded
|
||||
* the yubico-piv-tool software
|
||||
* credentials to request certs from a Windows CA
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Generate the key:
|
||||
(--key[=STRING] is needed if the management key value is no longer the default value)
|
||||
|
||||
yubico-piv-tool -s 9a -a generate -o public.pem --key[=STRING]
|
||||
|
||||
|
||||
2. Request a certificate:
|
||||
|
||||
yubico-piv-tool -a verify-pin -P 123456 -s 9a -a request-certificate \
|
||||
-S "/CN=example/O=test/" -i public.pem -o request.csr
|
||||
|
||||
3. Submit the request to the Windows CA:
|
||||
(this step must be run on a windows machine that know about the CA)
|
||||
|
||||
certreq -submit -attrib "CertificateTemplate:User" request.csr cert.crt
|
||||
|
||||
4. Load the certificate on the YubiKe:
|
||||
(--key[=STRING] is needed if the management key value is not the default value)
|
||||
|
||||
yubico-piv-tool -s 9a -a import-certificate -i cert.crt --key[=STRING]
|
||||
|
||||
5. For it to be useful in windows a chuid must be set as well:
|
||||
(only if that wasn't done earlier)
|
||||
(--key[=STRING] is needed if the management key value is no longer the default value)
|
||||
|
||||
yubico-piv-tool -a set-chuid --key[=STRING]
|
||||
@@ -1,6 +1,4 @@
|
||||
YKCS11
|
||||
------
|
||||
|
||||
== YKCS11
|
||||
This is a PKCS#11 module that allows to communicate with the PIV
|
||||
application running on a YubiKey.
|
||||
|
||||
@@ -10,18 +8,14 @@ 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
|
||||
~~~~~~~~
|
||||
|
||||
=== BUILDING
|
||||
YKCS11 is automatically built as part of `yubico-piv-tool` and the
|
||||
following command will suffice
|
||||
following command will suffice:
|
||||
|
||||
----
|
||||
yubico-piv-tool$ autoreconf --install
|
||||
yubico-piv-tool$ ./configure
|
||||
yubico-piv-tool$ make
|
||||
yubico-piv-tool$ sudo make install
|
||||
----
|
||||
$ 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
|
||||
@@ -31,9 +25,7 @@ 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
|
||||
~~~~~~~~~~~
|
||||
|
||||
=== 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).
|
||||
@@ -47,9 +39,7 @@ 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
=== 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.
|
||||
|
||||
@@ -84,9 +74,7 @@ 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
|
||||
^^^^^^^^^^^
|
||||
|
||||
==== 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:
|
||||
@@ -100,9 +88,7 @@ The mapping is as follows:
|
||||
|3|9d
|
||||
|===
|
||||
|
||||
PINs and Management Key
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
==== PINs and Management Key
|
||||
The default user PIN for the YubiKey is `123456`. +
|
||||
The default management key is
|
||||
`010203040506070801020304050607080102030405060708`. +
|
||||
@@ -119,9 +105,7 @@ 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 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
|
||||
@@ -129,16 +113,12 @@ 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
|
||||
^^^^^^^^^
|
||||
|
||||
==== 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
|
||||
----
|
||||
$ autoreconf --install
|
||||
$ ./configure --enable-ykcs11-debug
|
||||
$ make
|
||||
$ sudo make install
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
Yubico PIV Tool
|
||||
===============
|
||||
|
||||
== Yubico PIV Tool
|
||||
The YubiKey supports the Personal Identity Verification (PIV) card
|
||||
interface specified in NIST SP 800-73 document "Cryptographic
|
||||
Algorithms and Key Sizes for PIV". PIV enables you to perform RSA or
|
||||
@@ -11,9 +9,7 @@ hardware functionality.
|
||||
|
||||
* PIV Standards http://csrc.nist.gov/groups/SNS/piv/standards.html
|
||||
|
||||
General information
|
||||
-------------------
|
||||
|
||||
=== General information
|
||||
The default PIN code is 123456. The default PUK code is 12345678.
|
||||
|
||||
The default 3DES management key (9B) is
|
||||
@@ -31,57 +27,51 @@ 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 YubiKey for real use
|
||||
--------------------------------
|
||||
|
||||
=== Preparing a YubiKey for real use
|
||||
You would typically change the management key to make sure nobody but
|
||||
you can modify the state of the PIV application on the YubiKey. 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"'`
|
||||
echo $key
|
||||
yubico-piv-tool -a set-mgm-key -n $key
|
||||
$ key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
|
||||
$ echo $key
|
||||
$ yubico-piv-tool -a set-mgm-key -n $key
|
||||
|
||||
The PIN and PUK should be changed as well.
|
||||
|
||||
pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
|
||||
echo $pin
|
||||
$ pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
|
||||
$ echo $pin
|
||||
|
||||
puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
|
||||
echo $puk
|
||||
$ puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
|
||||
$ echo $puk
|
||||
|
||||
yubico-piv-tool -a change-pin -P 123456 -N $pin
|
||||
yubico-piv-tool -a change-puk -P 12345678 -N $puk
|
||||
|
||||
Other useful commands
|
||||
---------------------
|
||||
$ yubico-piv-tool -a change-pin -P 123456 -N $pin
|
||||
$ yubico-piv-tool -a change-puk -P 12345678 -N $puk
|
||||
|
||||
=== Other useful commands
|
||||
To generate a new private key:
|
||||
|
||||
yubico-piv-tool -k $key -a generate -s 9c
|
||||
$ yubico-piv-tool -k $key -a generate -s 9c
|
||||
|
||||
To reset PIN/PUK retry counter AND codes (default pin 123456 puk
|
||||
12345678):
|
||||
|
||||
yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
|
||||
$ yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
|
||||
|
||||
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).
|
||||
|
||||
yubico-piv-tool -a verify-pin -P 471112
|
||||
yubico-piv-tool -a verify-pin -P 471112
|
||||
yubico-piv-tool -a verify-pin -P 471112
|
||||
yubico-piv-tool -a verify-pin -P 471112
|
||||
yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
yubico-piv-tool -a reset
|
||||
|
||||
Software
|
||||
--------
|
||||
$ yubico-piv-tool -a verify-pin -P 471112
|
||||
$ yubico-piv-tool -a verify-pin -P 471112
|
||||
$ yubico-piv-tool -a verify-pin -P 471112
|
||||
$ yubico-piv-tool -a verify-pin -P 471112
|
||||
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789
|
||||
$ yubico-piv-tool -a reset
|
||||
|
||||
=== Software
|
||||
Card management has been tested with the tools from the OpenSC
|
||||
project, specifically piv-tool, and Yubico's PIV software (see
|
||||
below). Basic features should work with any PIV compliant
|
||||
@@ -93,9 +83,7 @@ middleware.
|
||||
* https://github.com/OpenSC/OpenSC/wiki/US-PIV
|
||||
* https://github.com/OpenSC/OpenSC/wiki/PivTool
|
||||
|
||||
Card Holder Unique Identifier
|
||||
-----------------------------
|
||||
|
||||
=== Card Holder Unique Identifier
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user