diff --git a/README b/README index 89054d3..b0ac4a8 100644 --- a/README +++ b/README @@ -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 diff --git a/doc/Android_code_signing.adoc b/doc/Android_code_signing.adoc deleted file mode 100644 index 1826b67..0000000 --- a/doc/Android_code_signing.adoc +++ /dev/null @@ -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 ----- diff --git a/doc/Attestation.adoc b/doc/Attestation.adoc index c980e02..bbdf1d2 100644 --- a/doc/Attestation.adoc +++ b/doc/Attestation.adoc @@ -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 diff --git a/doc/Certificate_Authority.adoc b/doc/Certificate_Authority.adoc deleted file mode 100644 index 13a96fb..0000000 --- a/doc/Certificate_Authority.adoc +++ /dev/null @@ -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< 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<yubico-internal-https-subca-$user-crt.conf< 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<yubico-internal-https-ee-$host-crt.conf< ~/.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. diff --git a/doc/SSH_with_PIV_and_PKCS11.adoc b/doc/SSH_with_PIV_and_PKCS11.adoc deleted file mode 100644 index 863b5d7..0000000 --- a/doc/SSH_with_PIV_and_PKCS11.adoc +++ /dev/null @@ -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 diff --git a/doc/Windows_certificate.adoc b/doc/Windows_certificate.adoc deleted file mode 100644 index ede262d..0000000 --- a/doc/Windows_certificate.adoc +++ /dev/null @@ -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] diff --git a/doc/YKCS11_release_notes.adoc b/doc/YKCS11_release_notes.adoc index 24efefa..9f8c600 100644 --- a/doc/YKCS11_release_notes.adoc +++ b/doc/YKCS11_release_notes.adoc @@ -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 diff --git a/doc/YubiKey_PIV_introduction.adoc b/doc/YubiKey_PIV_introduction.adoc index a8ee724..b1af69e 100644 --- a/doc/YubiKey_PIV_introduction.adoc +++ b/doc/YubiKey_PIV_introduction.adoc @@ -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