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 ECC sign/decrypt operations using a private key stored on the smartcard, through common interfaces like PKCS#11. This project contain the library, tools and PKCS#11 module to interact with the hardware functionality.

General information

The default PIN code is 123456. The default PUK code is 12345678.

The default 3DES management key (9B) is 010203040506070801020304050607080102030405060708.

The following key slots exists:

  • 9A, 9C, 9D, 9E: RSA 1024, RSA 2048, or ECC secp256r1 keys (algorithms 6, 7, 11 respectively).

  • 9B: Triple-DES key (algorithm 3) for PIV management.

The maximum size of stored objects is 2025/3049 bytes for current versions of YubiKey NEO and YubiKey 4, respectively.

Currently all functionality are available over both contact and contactless interfaces (contrary to what the specifications mandate).

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

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
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

To generate a new private key:

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

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

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 middleware.

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 contents change.