edent
96 lines
3.6 KiB
Plaintext
96 lines
3.6 KiB
Plaintext
== 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.
|
|
|
|
* PIV Standards https://csrc.nist.gov/groups/SNS/piv/standards.html
|
|
|
|
=== 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.
|
|
All of these invocations will leave traces of keys and pins in the command line
|
|
history, this can be avoided by leaving the argument out all-together and the
|
|
software will ask for key/pin to be input. For the management key option (-k)
|
|
this is achieved by leaving out the value but will specifying -k.
|
|
|
|
$ key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
|
|
$ echo $key
|
|
$ yubico-piv-tool -aset-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 -achange-pin -P123456 -N$pin
|
|
$ yubico-piv-tool -achange-puk -P12345678 -N$puk
|
|
|
|
=== Other useful commands
|
|
To generate a new private key:
|
|
|
|
$ yubico-piv-tool -k$key -agenerate -s9c
|
|
|
|
To reset PIN/PUK retry counter AND codes (default pin 123456 puk
|
|
12345678):
|
|
|
|
$ yubico-piv-tool -k$key -averify -P$pin -apin-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 -averify-pin -P471112
|
|
$ yubico-piv-tool -averify-pin -P471112
|
|
$ yubico-piv-tool -averify-pin -P471112
|
|
$ yubico-piv-tool -averify-pin -P471112
|
|
$ yubico-piv-tool -achange-puk -P471112 -N6756789
|
|
$ yubico-piv-tool -achange-puk -P471112 -N6756789
|
|
$ yubico-piv-tool -achange-puk -P471112 -N6756789
|
|
$ yubico-piv-tool -achange-puk -P471112 -N6756789
|
|
$ yubico-piv-tool -areset
|
|
|
|
=== 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.
|
|
|
|
* https://github.com/OpenSC/OpenSC/wiki
|
|
* https://developers.yubico.com/yubico-piv-tool/
|
|
* https://developers.yubico.com/yubikey-piv-manager/
|
|
* https://github.com/OpenSC/OpenSC/wiki/US-PIV
|
|
* https://github.com/OpenSC/OpenSC/wiki/PivTool
|
|
|
|
=== 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.
|