yubico-piv-tool (1) Linux Manual Page

yubico-piv-tool – Yubico PIV tool

Synopsis

yubico-piv-tool [,OPTIONS/]…

Description

yubico-piv-tool 1.1.1

-h, –help

Print help and exit

–full-help

Print help, including hidden options, and exit

-V, –version

Print version and exit

-v, –verbose[=,INT/]

Print more information (default=`0′)

-r, –reader=,STRING/

Only use a matching reader (default=`Yubikey’)

-k, –key[=,STRING/]

Authentication key to use (default=`010203040506070801020304050607080102030405060708′)

-a, –action=,ENUM/

Action to take (possible values="version", "generate", "set-mgm-key", "reset", "pin-retries", "import-key", "import-certificate", "set-chuid", "request-certificate", "verify-pin", "change-pin", "change-puk", "unblock-pin", "selfsign-certificate", "delete-certificate", "read-certificate", "status", "test-signature", "test-decipher", "list-readers")

Multiple actions may be given at once and will be executed in order for example –action=,verify-pin/ –action=,request-certificate/

-s, –slot=,ENUM/

What key slot to operate on (possible values="9a", "9c", "9d", "9e", "82", "83", "84", "85", "86", "87", "88", "89", "8a", "8b", "8c", "8d", "8e", "8f", "90", "91", "92", "93", "94", "95")

9a is for PIV Authentication 9c is for Digital Signature (PIN always checked) 9d is for Key Management 9e is for Card Authentication (PIN never checked) 82-95 is for Retired Key Management

-A, –algorithm=,ENUM/

What algorithm to use (possible values="RSA1024", "RSA2048", "ECCP256", "ECCP384" default=`RSA2048′)

-H, –hash=,ENUM/

Hash to use for signatures (possible values="SHA1", "SHA256", "SHA384", "SHA512" default=`SHA256′)

-n, –new-key=,STRING/

New authentication key to use

–pin-retries=,INT/

Number of retries before the pin code is blocked

–puk-retries=,INT/

Number of retries before the puk code is blocked

-i, –input=,STRING/

Filename to use as input, – for stdin (default=`-‘)

-o, –output=,STRING/

Filename to use as output, – for stdout (default=`-‘)

-K, –key-format=,ENUM/

Format of the key being read/written (possible values="PEM", "PKCS12", "GZIP", "DER" default=`PEM’)

-p, –password=,STRING/

Password for decryption of private key file

-S, –subject=,STRING/

The subject to use for certificate request

The subject must be written as: /CN=host.example.com/OU=test/O=example.com/

-P, –pin=,STRING/

Pin/puk code for verification

-N, –new-pin=,STRING/

New pin/puk code for changing

–pin-policy=,ENUM/

Set pin policy for action generate or import-key (possible values="never", "once", "always")

–touch-policy=,ENUM/

Set touch policy for action generate, import-key or set-mgm-key (possible values="never", "always")

Examples

For more information about what’s happening –verbose can be added to any command. For much more information –verbose=2 may be used.

Display what version of the application is running on the YubiKey:

yubico-piv-tool -a version

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

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 \
  -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 \
  -a verify -a selfsign

Import a certificate from stdin:

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 \
  -a import-key -a import-cert

Import a certificate which is larger than 2048 bytes and thus requires compression in order to fit:

  openssl x509 -in cert.pem -outform DER | gzip -9 > der.gz
  yubico-piv-tool -s 9c -i der.gz -K GZIP -a import-cert

Change the management key used for administrative authentication:

yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
  -a set-mgm-key

Delete a certificate in slot 9a:

  yubico-piv-tool -a delete-certificate -s 9a

Show some information on certificates and other data:

  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