PIV Tool Common Tasks
For a list of all available options --help can be given. For more information about what’s happening --verbose can be added to any command. For much more information --verbose=2 may be used.
YubiKey Related Tasks
Change the management key
Change the management key used for administrative authentication:
yubico-piv-tool -aset-mgm-key
See set-mgm-key.
Display PIV tool version
Display PIV tool version running on the YubiKey:
yubico-piv-tool -aversion
See version.
Generate a new ECC-P256 key
Generate a new ECC-P256 key on device in slot 9a and print the public key on stdout:
yubico-piv-tool -s9a -AECCP256 -agenerate
See generate.
Import a key into slot 85
Import a key into slot 85 and set the touch policy: Both options only available on YubiKey 4 and 5:
yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem
See import-key.
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
See verify-pin.
Reset the application after PIN/PUK modified
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
See verify-pin, change-puk, and reset.
Run a signature test
Read out the certificate from a slot and then run a signature test:
yubico-piv-tool -aread-cert -s9a
yubico-piv-tool -averify-pin -atest-signature -s9a
See read-certificate and verify-pin.
Set a random chuid
Set a random chuid, import a key, and import a certificate from a PKCS12 file, into slot 9c:
yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key -aimport-cert
See set-chuid, import-key, and import-certificate.
Set the touch policy
Import a key into slot 85 and set the touch policy: Both options only available on YubiKey 4 and 5 or newer:
yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem
See import-key and PIV Tool Options.
Certificate Related Tasks
Compress a large certificate
Import a large certificate and use yubico-piv-tool to apply GZIP compression. Compression is required for certificates larger than 2048 bytes in order to have fit:
yubico-piv-tool -s9c -icert.pem --compress -aimport-cert
See import-certificate and generate.
Delete a certificate
Delete a certificate in slot 9a, with management key being asked for:
yubico-piv-tool -adelete-certificate -s9a -k
See delete-certificate.
Generate a certificate request
Generate a certificate request with public key from stdin and print the resulting request on stdout:
yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest
See generate.
Generate a self-signed certificate
Generate a self-signed certificate with public key from stdin and print the certificate, for later import on stdout:
yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify -aselfsign
See generate.
Import a certificate
Import a certificate from stdin:
yubico-piv-tool -s9a -aimport-certificate
See import-certificate and generate.
Import a large certificate
Import a large certificate that requires compression. Certificates larger than 2048 bytes require compression in order to fit:
openssl x509 -in cert.pem -outform DER | gzip -9 > der.gz
yubico-piv-tool -s9c -ider.gz -KGZIP -aimport-cert
See import-certificate.
Import a large certificate
Import a certificate which is larger than 2048 bytes and have the yubico-piv-tool do the GZIP compression in order to fit:
yubico-piv-tool -s9c -icert.pem --compress -aimport-cert
See import-certificate.
Read out the certificate
Read out the certificate from a slot and then run a signature test:
yubico-piv-tool -aread-cert -s9a
yubico-piv-tool -averify-pin -atest-signature -s9a
See read-certificate, verify-pin, and test-signature.