PIV Tool Command, Options and Actions

yubico-piv-tool [Option] …

Use the PIV tool command options.

PIV Tool Options

Option	Description
`-h, --help`	Print help and exit
`-a, --action ENUM`	Action to take. Possible values: `attest`, `change-pin`, `change-puk`, `delete-certificate`, `delete-key`, `generate`, `import-certificate`, `import-key`, `list-readers`, `move-key`, `pin-retries`, `read-certificate`, `read-object`, `read-public-key`, `request-certificate`, `reset`, `selfsign-certificate`, `set-chuid`, `set-ccc`, `set-mgm-key`, `status`, `test-decipher`, `test-signature`, `unblock-pin`, `verify-bio`, `verify-pin`, `version`, `write-object` Multiple actions may be given at once and are executed in order, for example: `--action=verify-pin --action=request-certificate` See PIV Tool action Command Parameters for descriptions.
`-A,` `--algorithm ENUM`	The algorithm to use. Possible values: `ECCP256`, `ECCP384`, `ED25519`, `RSA1024`, `RSA2048`, `RSA3072`, `RSA4096`, `X25519`. Default: `RSA2048`
`--attestation`	Add attestation cross-signature. Default: `off`
`--compress`	Compress a large certificate using GZIP before import. Default: `off`
`--enc`	Communication with the YubiKey is done over an encrypted channel. Default: `off`
`-f, --format ENUM`	Format of data for write/read object. Possible values: `hex`, `base64`, `binary`. Default: `hex`
`-full-help`	Print help, including hidden options, and exit.
`-global`	Reset the whole device over all applications. Default: `off`
`-H, --hash ENUM`	Hash to use for signatures. Possible values: `SHA1`, `SHA256`, `SHA384`, `SHA512`. Default: `SHA256`
`-i, --input STRING`	Filename to use as input, `-` for stdin. Default: `-`
`--id INT`	Id of object for write/read object.
`-k`, `--key [STRING]`	Management key to use, if no value specified, PIV tool prompts for key. Default: `010203040506070801020304050607080102030405060708`
`-K,` `--key-format ENUM`	Format of the key being read/written. Possible values: `PEM`, `PKCS12`, `GZIP`, `DER`, `SSH`. Default: `PEM`
`-m,` `--new-key-algo ENUM`	New management key algorithm to use for action: set-mgm-key. Possible values: `AES128`, `AES192`, `AES256`, `TDES`. Default: `TDES`
`-n,` `--new-key STRING`	New management key to use for action: `set-mgm-key`. If omitted, PIV tool prompts for key.
`-N,` `--new-pin STRING`	New pin/puk code for changing. If omitted, PIV tool prompts for pin/puk.
`-o,` `--output STRING`	Filename to use as output. Possible values: none or filename. Use `-` for stdout. Default: `-`, output is printed to `stdout`.
`-p,` `--password STRING`	Password for decryption of private key file. If omitted, PIV tool prompts for password.
`-P,` `--pin STRING`	Pin/puk code for verification. If omitted, PIV tool prompts for pin/puk.
`--pin-policy ENUM`	Set pin policy for action: generate or import-key. Only available on YubiKey 4 or newer. Possible values: `never`, `once`, `always` `matchonce`, `matchalways`
`--pin-retries INT`	Number of retries before the pin code is blocked.
`--puk-retries INT`	Number of retries before the puk code is blocked.
`-r`, `--reader STRING`	Only use a matching reader. Default: `Yubikey`
`-s, --slot ENUM`	The key slot to operate on. (1) Possible values: `82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d,` `8e, 8f, 90, 91, 92, 93, 94, 95, 9a, 9c, 9d, 9e, f9` where - `9a` for PIV Authentication. `9c` for Digital Signature (PIN always checked). `9d` for Key Management. `9e` for Card Authentication (PIN never checked). `82-95` for Retired Key Management. `f9` for Attestation.
`-S,` `--subject STRING`	The subject to use for certificate request. The subject string must be written as: `/CN=host.example.com/OU=test/O=example.com/`
`--scp11`	Use encrypted communication in accordance with SCP11b. DEPRECATED as of yubico-piv-tool version 2.7.2. Use the `--enc` flag.
`--serial INT`	Serial number of the self-signed certificate.
`--to-slot ENUM`	The slot to move an existing key to. (1) Possible values: `82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d,` `8e, 8f, 90, 91, 92, 93, 94, 95, 9a, 9c, 9d, 9e, f9` where - `9a` for PIV Authentication. `9c` for Digital Signature (PIN always checked). `9d` for Key Management. `9e` for Card Authentication (PIN never checked). `82-95` for Retired Key Management. `f9` for Attestation.
`--touch-policy ENUM`	Set touch policy for action: `generate`, `import-key` or `set-mgm-key`. Requires YubiKey 4 or newer. Possible values: `never`, `always`, `cached`
`-v`, `--verbose [INT]`	Print more information. Default: `0`
`-V, --version`	Print version and exit.
`--valid-days INT`	Time (in days) until the self-signed certificate expires. Default: `365`

(1) For addition information on slot values, see PIV Certificate Slots.

PIV Tool action Command Parameters

Syntax

yubico-piv-tool --action ENUM <options>...

yubico-piv-tool -aENUM <options>...

Description

The tables lists the possible actions for the PIV tool command option --action ENUM. Where ENUM is replaced with options from the table. See the balance of this chapter for additional usage information.

Parameters

Action	Description
attest	Generate an X509 certificate for an asymmetric key that was generated inside the YubiKey.
change-pin	Change the PIN code required to access the PIV interface.
change-puk	Change the PUK.
`delete-cert`, delete-certificate	Delete a certificate from a specific slot.
delete-key	Delete a key from a specific slot.
generate	Generate an RSA or an EC key on a specific slot.
`import-cert`, import-certificate	Import an X509 certificate into a specific slot.
import-key	Import a private key into a specific slot.
list-readers	List the accessible smart card readers.
move-key	Move a key between slots.
pin-retries	Change the number of retries allowed before the PIN or the PUK are blocked.
`read-cert`, read-certificate	Return the X509 certificate stored on a specific slot.
read-object	Return the content of a slot.
read-public-key	Return the public key stored on a specific slot.
`request`, `request-certificate`	Generate a certification request for an asymmetric key stored on a specific slot. See generate.
reset	Reset the YubiKey PIV interface.
`selfsign`, `selfsign-certificate`	Generate a self signed X509 certificate for an asymmetric key stored on a specific slot. See generate.
set-ccc	Set a new CCC.
set-chuid	Set or change the Card Holder Unique Identifier.
set-mgm-key	Set the management key required to perform administrative actions on the PIV interface.
`sign` sign-data	Sign input data.
status	Return the device metadata and content.
test-decipher	Test the decryption function.
test-signature	Test the digital signing function.
unblock-pin	Set a new PIN code after entered incorrectly too many times.
`verify-bio`	Verify the PIN code required to access the PIV interface on a bio Yubikey. See generate.
`verify`, `verify-pin`	Verify the PIN code required to access the PIV interface. See generate.
version	Return the device firmware version.
`write-object`	Store an object in a slot. See read-object.

attest

Syntax

yubico-piv-tool --action=attest --slot ENUM --output=[STRING]

yubico-piv-tool -a attest

Description

The attestation, attest, feature is only available in YubiKey 4.3 and above.

Generate an X509 certificate for an asymmetric key that was generated inside the YubiKey.

See attestation in this guide, PIV Tool Attestation.
See attestation with a developer’s product, PIV Attestation.

Examples

yubico-piv-tool --action=attest --slot=f9 --out SlotF9Intermediate.pem

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot ENUM`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: none, value required
`-o,` `--output=[STRING]`	Required	Filename to use as output. If not specified, output is printed to `stdout`.	none or filename. Default: `-` for stdout

change-pin

Syntax

yubico-piv-tool --action=change-pin --new-pin STRING

yubico-piv-tool -a change-pin -N <string>

Description

Change the Personal Identification Number (PIN) code required to access the PIV interface.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-N,` `--new-pin STRING`	Required	New pin/puk code for changing. If a new PUK is not provided, PIV Tool prompts to provide one	Default: none

change-puk

Syntax

yubico-piv-tool --action=change-puk --new-pin STRING

yubico-piv-tool -a change-puk -N <string>

Description

Change the Personal Unblocking Key (PUK).

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-N,` `--new-pin STRING`	Required	New pin/puk code for changing. If a new PUK is not provided, PIV Tool prompts to provide one	Default: none

delete-certificate

Syntax

yubico-piv-tool --action=delete-certificate --slot ENUM --key [STRING]

yubico-piv-tool -a delete-certificate -s ENUM -k [STRING]

Description

Deletes a certificate from the specified slot. The corresponding private key is not deleted unless it is overwritten.

Deleting a certificate requires authentication by providing the management key. If no management key is provided, the PIV tool attempts authentication using the default management key.

Important

It is strongly recommended you change the Yubikey PIN, PUK, and management key before you start using the Yubikey.

Examples

$ yubico-piv-tool -a delete-certificate -s <slot> -k

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot ENUM`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-k, --key [STRING]`	Required	Management key to use. If no value is specified, PIV tool prompts for value	Default: `0102030405060708` `0102030405060708` `0102030405060708`

delete-key

Syntax

$ yubico-piv-tool -a delete-key -s <slot> -k

Description

Deletes a key from the specified PIV slot. The function requires YubiKey 5.7 or higher.

Note

This actions deletes only the key, not the certificate. So if the slot already stores a certificate, it might still look populated even if the key is no longer there.

Deleting a key is an action that requires authentication, which is done by providing the management key. If no management key is provided, the tool tries to authenticate using the default management key.

Important

It is strongly recommended you change the Yubikey PIN, PUK, and management key before you start using the Yubikey.

Examples

$ yubico-piv-tool -a delete-key -s 9c -k
Enter Password:
Enter management key:
Successfully deleted key.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot ENUM`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-k, --key [STRING]`	Required	Management key to use. If no value is specified, PIV tool promps for value	Default: `0102030405060708` `0102030405060708` `0102030405060708`

generate

Syntax

$ yubico-piv-tool -a generate -s <slot> -k [ -A <key algorithm> -o <public key file> ]

$ yubico-piv-tool -a verify-pin -a selfsign -s <slot> -S <subject dn> [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <public key file> --serial <cert serial number> --valid-days DAYS -o <cert file> ]

$ yubico-piv-tool -a verify-pin -a request-certificate -s <slot> -S <subject dn> [ -P <PIN> -i <public key file> -o <cert request file> ]

$ yubico-piv-tool -a import-certificate -s <slot> -k [ -o <cert file> ]

Description

Generate an RSA or an EC key on a specific slot. This requires a sequence of action commands. Completed key generation can include generate, selfsign, request-certificate, verify-pin or verify-bio, and import-certificate.

An occupied slot on the Yubikey PIV interface usually contains a private key, a public key and an X509 certificate. The key pair generate, the certificate generation and the certificate import are done using different actions in the right order.

Generating a key pair sets the public key as an output (action generate). The public key is used to either generate a self signed certificate (action selfsign) or a certificate request (action request-certificate). The resulting certificate should then be imported into the same slot (action import-certificate).

Generating the key pair and importing the certificate are both actions that require authentication, which is done by providing the management key. If no management key is provided, the tool will try to authenticate using the default management key.

Important

It is strongly recommended to change the Yubikey’s PIN, PUK and management key before start using it

While generating the certificate/certificate request does not require authentication, the signing operation does require verifying the PIN code or the fingerprint if the YubiKey supports Bio verification, which has to be done in an action that must take place before the signing action, otherwise the operation fails. Use -a verify-pin to verify the PIN and -a verify-bio for fingerprint verification.

Examples

Example 1: Self signed certificate on slot 9a

$ yubico-piv-tool -a generate -s 9a -A ECCP256 -k
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwyLPuYF7xF4iQ+5VWUnDQsMSf9O7
Jc1gBDHQJ0kfYnZ8tV2OFk3JFyfZDL9g9g3eFaH00dzstxH7te64DtYepw==
-----END PUBLIC KEY-----
Successfully generated a new private key.

$ yubico-piv-tool -a verify-pin -a selfsign -s 9a -S '/CN=piv_auth/OU=test/O=example.com/'
Enter PIN:
Successfully verified PIN.
Please paste the public key...
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwyLPuYF7xF4iQ+5VWUnDQsMSf9O7
Jc1gBDHQJ0kfYnZ8tV2OFk3JFyfZDL9g9g3eFaH00dzstxH7te64DtYepw==
-----END PUBLIC KEY-----
-----BEGIN CERTIFICATE-----
MIIBujCCAWCgAwIBAgIJAJKWdUFfuvqiMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTIxMzM0NTdaFw0yMDA4MTExMzM0NTdaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABMMiz7mBe8ReIkPuVVlJw0LDEn/TuyXNYAQx0CdJ
H2J2fLVdjhZNyRcn2Qy/YPYN3hWh9NHc7LcR+7XuuA7WHqejUzBRMB0GA1UdDgQW
BBQS0iNbyP8W817uCk/2lPd19ZvNRDAfBgNVHSMEGDAWgBQS0iNbyP8W817uCk/2
lPd19ZvNRDAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQC5CTvl
LE0htwa89LBRRSL2BWHqciSLvqx9azjJfd63JAIgcAJSIhWpiXeBcGZdcTbnmkqU
kWu4LDU2ymBRp8pp4Iw=
-----END CERTIFICATE-----
Successfully generated a new self signed certificate.

$ yubico-piv-tool -a import-certificate -s 9a -k
Please paste the certificate...
-----BEGIN CERTIFICATE-----
MIIBujCCAWCgAwIBAgIJAJKWdUFfuvqiMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTIxMzM0NTdaFw0yMDA4MTExMzM0NTdaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABMMiz7mBe8ReIkPuVVlJw0LDEn/TuyXNYAQx0CdJ
H2J2fLVdjhZNyRcn2Qy/YPYN3hWh9NHc7LcR+7XuuA7WHqejUzBRMB0GA1UdDgQW
BBQS0iNbyP8W817uCk/2lPd19ZvNRDAfBgNVHSMEGDAWgBQS0iNbyP8W817uCk/2
lPd19ZvNRDAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQC5CTvl
LE0htwa89LBRRSL2BWHqciSLvqx9azjJfd63JAIgcAJSIhWpiXeBcGZdcTbnmkqU
kWu4LDU2ymBRp8pp4Iw=
----END CERTIFICATE-----
Successfully imported a new certificate.

It is also possible to combine all these commands above into one single command (notice the order of the actions):

$ yubico-piv-tool -a generate -a verify-pin -a selfsign -a import-certificate -s 9a -k -A ECCP256 -S '/CN=piv_auth/OU=test/O=example.com/'

Example 2: generate Signed certificate on slot 9c

$ yubico-piv-tool -a generate -s 9c -A RSA2048 -o pub.key
Successfully generated a new private key.

$ yubico-piv-tool -a verify-pin -a request-certificate -s 9c -S '/CN=digi_sign/OU=test/O=example.com/' -i pub.key -o csr.pem
Enter PIN:
Successfully verified PIN.
Successfully generated a certificate request.

After sending the certificate request to the CA and getting a signed certificate:

$ yubico-piv-tool -a import-certificate -s 9c -i cert.pem
Successfully imported a new certificate.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot ENUM`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-k, --key [STRING]`	Required	Management key to use. If no value is specified, PIV tool prompts for value	Default: `0102030405060708` `0102030405060708` `0102030405060708`
`-S,` `--subject STRING`	Required	The subject to use for certificate request. The string must be written as: `/CN=host.example.com/` `OU=test/O=example.com/`
`-A`, `--algorithm ENUM`	Optional	The algorithm to use to generate the key pair	`RSA1024, RSA2048`, `RSA3072, RSA4096,` `ECCP256, ECCP384,` `ED25519, X25519` * Requires YubiKey 5.7 or newer Default: `RSA2048`
`-o,` `--output=[STRING]`	Optional	Filename to use as certificate file. If not specified, output is printed to `stdout`.	none or filename. Default: `-` for stdout
`-P,` `--pin STRING`	Optional	Pin/puk code for verification. If omitted, PIV tool prompts for pin/puk
`--pin-policy ENUM`	Optional	Set pin policy for action: generate or import-key. Only available on YubiKey 4 or newer.	Values Bio key verification: `never`, `once`, `always` `matchonce` Value PIN key verification: `matchalways` Default: slot 9c, `always` slot 9a, 9d and 9e, `once`
`--touch-policy ENUM`	Optional	Set touch policy for the slot containing the key. Requires YubiKey 4 or newer.	`never, always, caches` Default: `never`
`-i, --input STRING`	Optional	Filename to use as input. If left out, input is read from `Stdin`.	None or file name Default: `-` for stdin The only supported format for public key is PEM.
`--serial INT`	Optional	Serial number of the self- signed certificate
`--valid-days INT`	Optional	Time (in days) until the self-signed certificate expires	Default: `365`
`-o,` `--output=[STRING]`	Required	Filename to use as output. If not specified, output is printed to `stdout`.	none or filename. Default: `-` for stdout

import-certificate

Syntax

$ yubico-piv-tool -a import-certificate -s <slot> -k [ -i <input file> -K <input file format> ]

Description

Import an X509 certificate into a specific slot.

Part of generating an RSA or an EC key on a specific slot. This requires a sequence of action commands. Completed key generation can include generate, selfsign, request-certificate, verify-pin or verify-bio, and import-certificate. See generate.

The import-key command option precedes import-certificate. See import-key.

Examples

$ yubico-piv-tool -a import-certificate -s <slot> -k [ -o <cert file> ]

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-k, --key [STRING]`	Required	Management key to use. If no value is specified, a key asked for.	Default: `0102030405060708` `0102030405060708` `0102030405060708`
`-o,` `--output=[STRING]`	Optional	Filename to use as certificate file. If not specified, output is printed to `stdout`.	none or filename. Default: `-` for stdout

import-key

Syntax

$ yubico-piv-tool -a import-key -s <slot> -k [options]

Description

Imports a key, a certificate, or both into the Yubikey PIV interface for a specific slot. The largest accepted keys are of size 2025/3049 bytes for current versions of YubiKey NEO and YubiKey 5, respectively. It is possible to import larger certificates, but that requires compression in order for it to fit (see examples bellow).

This action is also used to import decryption keys (aka. key management keys typically found in slot 9d) into the retired slots (slots 82-95)

Importing either a key or a certificate is an action that requires authentication, which is done by providing the management key. If no management key is provided, the tool will try to authenticate using the default management key.

Important

It is strongly recommended to change the Yubikey’s PIN, PUK and management key before start using it.

Examples

$ yubico-piv-tool -a import-key -s <slot> -k [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <input file> -p <input file password> -K <input file format> ]

$ yubico-piv-tool -a import-certificate -s <slot> -k [ -i <input file> -K <input file format> ]

$ yubico-piv-tool -a import-key -a import-certificate -s <slot> -k [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <input file> -p <input file password> -K <input file format> ]

$ yubico-piv-tool -a import-key -a import-certificate -s 9c -k -i key.pfx -K PKCS12
Enter Password:
Enter management key:
Successfully imported a new private key.
Successfully imported a new certificate.

$ yubico-piv-tool -a import-certificate -s 9c -k -i cert_large.gz -K GZIP
Successfully imported a new certificate.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-k, --key [STRING]`	Required	Management key to use. If no value is specified, a key asked for.	Default: `0102030405060708` `0102030405060708` `0102030405060708`
`-P,` `--pin STRING`	Optional	Pin/puk code for verification. If omitted, PIV tool prompts for pin/puk
`--pin-policy ENUM`	Optional	Set pin policy for action generate or import-key. Only available on YubiKey 4 or newer.	Possible values : `never`, `once`, `always` Values Bio key: `matchonce`, `matchalways` Default: slot 9c, `always` slot 9a, 9d and 9e, `once`
`--touch-policy ENUM`	Optional	Set touch policy for the slot containing the key. Requires YubiKey 4 or newer.	`never, always, caches` Default: `never`
`-i, --input STRING`	Optional	Filename to use as input. If left out, input is read from `Stdin`.	None or file name Default: `-` for stdin The only supported format for public key is PEM.
`-p,` `--password STRING`	Optional	Password for decryption of private key file. If omitted, PIV tool prompts for password
`-K,` `--key-format ENUM`	Optional	Format of the key being read/written.	`PEM, PKCS12, GZIP, DER, SSH` Default: `PEM`

list-readers

No sample available.

move-key

Syntax

$ yubico-piv-tool -a move-key -s <slot> --to-slot <slot> -k

Description

Moves a key from one PIV slot to another. The function requires YubiKey 5.7 or higher.

Note

This actions moves only the key, not the certificate. So if the slot already stores a certificate, it might still look populated even if the key is no longer there.

Moving a key is an action that requires authentication, which is done by providing the management key. If no management key is provided, the tool will try to authenticate using the default management key.

Important

It is strongly recommended to change the Yubikey’s PIN, PUK and management key before start using it.

Examples

$ yubico-piv-tool -a move-key -s 9c --to-slot 84 -k
Enter Password:
Enter management key:
Successfully moved key.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`--to-slot`	Required	Key slot to move the key to	`9a, 9c, 9d, 9e, 82,83, 84,` `85, 86, 87, 88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92`, `93, 94, 95, f9`
`-k,` `--key [STRING]`	Required	Management key to use. If no value is specified, a key asked for	Default: `0102030405060708` 0102030405060708`` `0102030405060708`

pin-retries

No sample available.

read-certificate

Syntax

$ yubico-piv-tool -a read-certificate -s <slot> [ -o <cert.pem> -K <cert file format> ]

Description

Returns the X509 certificate stored on a certain slot.

Examples

$ yubico-piv-tool -a read-cert -s 9a
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`.	`None` or file name Default: `Stdout`
`-K,` `--key-format`	Optional	Format of certificate being read	`PEM, DER, SSH` Default: `PEM`

read-object

Syntax

$ yubico-piv-tool -a read-object --id <object ID> [ -o <output file> -f <file format> ]

$ yubico-piv-tool -a write-object --id <object ID> -k [ -i <input file>  -f <file format>]

Description

The read-object syntax includes write-object syntax.

Reads and stores raw data into a PIV slot. The form and ID of the data are detailed in section 4.3 of the PIV Specification SP 800-73-4.

Writing an object is an action that requires authentication, which is done by providing the management key. If no management key is provided, the tool tries to authenticate using the default management key.

Important

It is strongly recommended to change the Yubikey’s PIN, PUK and management key before start using it.

Examples

$ yubico-piv-tool -a read-object --id 0x5fc10d
708202b2308202ae30820196a003020102020832b1fd4fd258f9bd300d06092a864886f70d01010b0500
303b3115301306035504030c0c4d616e6167656d656e74434131153013060355040a0c0c454a42434120
59756269636f310b3009060355040613025345301e170d3139303830383134333034325a170d32313038
30373134333034325a30203111300f06035504030c08757365725f333834310b30090603550406130253
453076301006072a8648ce3d020106052b810400220362000456444320b440fe49f312b023aa571da565
e9bc966dc928aef49c87e45d95cccf5b07fbe9e6620d2bb9d3c268671b2eed0e912c1dfae34f1e8f61a2
4565cb6498129618b96b7e3f38962796aa67382878cbe2cc1a8c369a55cecbd31b7a5cb032a37f307d30
0c0603551d130101ff04023000301f0603551d230418301680140c6d2aca0fe3aef788b50479477aba8a
87b08ad4301d0603551d250416301406082b0601050507030206082b06010505070304301d0603551d0e
04160414a508f3007b5344dc8efe08d87dfdbcb53191c7f3300e0603551d0f0101ff0404030205e0300d
06092a864886f70d01010b050003820101003993c325a5396ae1455e94d31dc6eda702b3e17b0f82de6d
1c22e994de13124022d7b127dff25a082c6f8a4ff74e0a965cb619bbc62787072b5d1ecb5a06e4b9d245
23534b1c4e6ac8265e8debb8111c62afbf8e1952e5ebd3ac81f6cf1900497719cb1ab60c1e92be9032db
1f69bf04d5def4fe2788de04452f2b01ced25fb186ce1b67c830dbbcc5e9d857951e347047c75f7456d4
2e9519694a7361f0b892d9acec10a55e5a61c483942543b13bd2c345b08ed1adc043647505a8d3ce2152
c4dfb8dc005e0fedc3d94aaf1e7e63b0c720c16481207451dd800e9cf7750c9bec580ce97aa540366ff1
f1ad5366fc3aac5563db73b6f44574968e3922e9e9fb710100fe00

Supported PIV Object IDs for read- and write-object

Type of Object Data	ASN.1 OID	ID
Card Capability Container	2.16.840.1.101.3.7.1.219.0	0x5fc107
Card Holder Unique Identifier	2.16.840.1.101.3.7.2.48.0	0x5fc102
X.509 Certificate for PIV Authentication	2.16.840.1.101.3.7.2.1.1	0x5fc105
Cardholder Fingerprints	2.16.840.1.101.3.7.2.96.16	0x5fc103
Security Object	2.16.840.1.101.3.7.2.144.0	0x5fc106
Cardholder Facial Image	2.16.840.1.101.3.7.2.96.48	0x5fc108
X.509 Certificate for Card Authentication	2.16.840.1.101.3.7.2.5.0	0x5fc101
X.509 Certificate for Digital Signature	2.16.840.1.101.3.7.2.1.0	0x5fc10a
X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.1.2	0x5fc10b
Printed Information	2.16.840.1.101.3.7.2.48.1	0x5fc109
Discovery Object	2.16.840.1.101.3.7.2.96.80	0x7e
Key History Object	2.16.840.1.101.3.7.2.96.96	0x5fc10c
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.1	0x5fc10d
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.2	0x5fc10e
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.3	0x5fc10f
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.4	0x5fc110
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.5	0x5fc111
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.6	0x5fc112
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.7	0x5fc113
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.8	0x5fc114
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.9	0x5fc115
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.10	0x5fc116
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.11	0x5fc117
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.12	0x5fc118
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.13	0x5fc119
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.14	0x5fc11a
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.15	0x5fc11b
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.16	0x5fc11c
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.17	0x5fc11d
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.18	0x5fc11e
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.19	0x5fc11f
Retired X.509 Certificate for Key Management	2.16.840.1.101.3.7.2.16.20	0x5fc120
Cardholder Iris Images	2.16.840.1.101.3.7.2.16.21	0x5fc121
Biometric Information Templates Group Templates	2.16.840.1.101.3.7.2.16.21	0x7f61
Secure Messaging Certificate Signer	2.16.840.1.101.3.7.2.16.21	0x5fc122
Pairing Code Reference Data Container	2.16.840.1.101.3.7.2.16.21	0x5fc123

Parameters

Parameter	Required Optional	Description	Possible values, Default
`--id INT`	Required	The ID of the object to write/read according to PIV Specifications
`-k,` `--key [STRING]`	Required	Management key to use. If no value is specified, a key asked for	Default: `0102030405060708` `0102030405060708` `0102030405060708`
`-i, --input`	Optional	Filename to use as input. If left out, input is read from `Stdin`	`None` or file name Default: `Stdin`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`	`None` or file name Default: `Stdout`
`-f, --format`	Optional	Format of data for write/read object	`hex, base64, binary` Default: `hex`

read-public-key

Syntax

$ yubico-piv-tool -a read-public-key -s <slot> [ -o <cert.pem> -K <cert file format> ]

Description

Returns the X509 public key stored on a certain slot.

Examples

$ yubico-piv-tool -a read-public-key -s 9a
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAntRh/Q1ILx5n3KJIUJCM
vW1aNGa5jjlEwMBBtFWOrgEmmHUK4BvyMIVZyL5kYZr9aJZdrRW0+ltzGWWDZ0ET
nZrYIqHuJZuCaLQNk6kN+KJfW0/QGgV6WxMwniBIDL924miUlTjt8FvnuiW3oAuC
xLVktNp9cPlzXlWKvHqZzwprhX1SQ9AApuKiABxxiPmVdo2qSFflKMTH3wL+DRCO
Nbc/YRiJqEjqub0p67TMkgoBUfpCLYFiMFaHj4cv/RsTho/A0osnql6JSesGkDJJ
YhHs5RCYytvgqpx8BQp1iEawSw15Fq1eJxUyFbyeHoUkwVfTNso39KnhgDhGt2Xf
IQIDAQAB
-----END PUBLIC KEY-----

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`.	`None` or file name Default: `Stdout`
`-K, --key-format`	Optional	Format of key being read.	`PEM` Default: `PEM`

request-certificate

Description

Generate a certification request for an asymmetric key stored on a specific slot.

Part of generating an RSA or an EC key on a specific slot. This requires a sequence of action commands. Completed key generation can include generate, selfsign, request-certificate, verify-pin or verify-bio, and import-certificate.

See generate.

Examples

$ yubico-piv-tool -a verify-pin -a request-certificate -s <slot> -S <subject dn> [ -P <PIN> -i <public key file> -o <cert request file> ]

reset

Syntax

$ yubico-piv-tool -a reset

Description

Erases all keys and certificates stored on the device and sets it to the default PIN, PUK and management key. This only affects the PIV application on the YubiKey, so any non-PIV configuration remains intact. Resetting the device does not erase the attestation key and certificate (slot f9) either, though they can be overwritten.

To reset the device, the PIN and the PUK need to be blocked. This happens when the wrong PIN and PUK is entered more than the number of their retries.

Global Reset:

Some YubiKeys with firmware version 5.7.0 or higher have support for a global support option. This option erases all data on the YubiKey and is not restricted to the PIV application. It also does not require that the PIN and PUK to be blocked.

Note

The global reset option cannot be used over an encrypted session.

Examples

$ 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

$ yubico-piv-tool -areset --global

Parameters

Parameter	Required Optional	Description	Possible values, Default
`--global`	Optional	Reset the whole device over all applications, including the PIV application	Default: `Off`

selfsign-certificate

Description

Generate a self signed X509 certificate for an asymmetric key stored on a specific slot.

Part of generating an RSA or an EC key on a specific slot. This requires a sequence of action commands. Completed key generation can include generate, selfsign, request-certificate, verify-pin or verify-bio, and import-certificate.

See generate.

Examples

$ yubico-piv-tool -a verify-pin -a selfsign -s <slot> -S <subject dn> [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <public key file> --serial <cert serial number> --valid-days DAYS -o <cert file> ]

set-ccc

No sample available.

set-chuid

No sample available.

set-mgm-key

No sample available.

sign-data

Syntax

$ yubico-piv-tool -a verify-pin --sign -s <slot> [ -H <hash algorithm> -A <key algorithm> -P <PIN code> -i <input data file> -o <signature file> ]

Description

Signs input data.

The signing operation requires verifying the PIN code or the fingerprint if the YubiKey supports Bio verification. Use -a verify-pin to verify the PIN and -a verify-bio for fingerprint verification.

Examples

$ yubico-piv-tool -a verify-pin --sign -s 9c -H SHA512 -A RSA2048 -i data.txt -o data.sig
Enter PIN:
Successfully verified PIN.
Signature successful!

$ openssl dgst -sha512 -verify pubkey.pem -signature data.sig data.txt
Verified OK

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-A,` `--algorithm`	Optional	The algorithm to use to generate the key pair	`RSA1024, RSA2048,` `RSA3072, RSA4096,` `ECCP256, ECCP384,` `ED25519, X25519` * Requires YubiKey 5.7 or newer Default: `RSA2048`
`-H, --hash`	Optional	Hash to use for signatures	`SHA1, SHA256, SHA384, SHA512` Default: `SHA256`
`-P, --pin`	Optional	Pin/puk code for verification. If omitted, pin/puk is asked for.
`-i, --input`	Optional	Filename to use as input. If left out, input is read from `Stdin`.	`None` or file name Default: `Stdin`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`.	`None` or file name Default: `Stdout`

status

Syntax

$ yubico-piv-tool -a status [ -s <slot> ]

Description

Lists the device’s meta data and the content of slots 9a, 9c, 9d and 9e. The content of slot f9 is listed if the slot is specified as an argument. This action, however, does not list the content of the retired slots (slots 82-95).

Examples

Example 1:

$ yubico-piv-tool -a status
Version:    4.4.0
Serial Number:      12345678
CHUID:      No data available
CCC:        No data available
Slot 9a:
        Private Key Algorithm:      RSA2048
        Public Key Algorithm:       RSA2048
        Subject DN:     CN=piv_auth, C=SE
        Issuer DN:      CN=TestCA, O=Yubico, C=SE
        Fingerprint:    4a1416fce853b29eaf520174bf8639d72ff30bd84e4586f81ac2a19eda43fdf1
        Not Before:     Aug  8 14:29:23 2019 GMT
        Not After:      Aug  7 14:29:23 2021 GMT
Slot 9c:
        Private Key Algorithm:      ECCP384
            Public Key Algorithm:   RSA2048
        Subject DN:     CN=sign, C=SE
        Issuer DN:      CN=TestCA, O=Yubico, C=SE
        Fingerprint:    803a89d5e196835d4a7e5e600e413fec1d3014712fcfd9e31fe15010829226dd
        Not Before:     Aug  8 14:29:50 2019 GMT
        Not After:      Aug  7 14:29:50 2021 GMT
        WARNING: Slot private key and certificate do not match
Slot 9d:
        Private Key Algorithm:      RSA2048
        Public Key Algorithm:       RSA2048
        Subject DN:     CN=key_mgm, C=SE
        Issuer DN:      CN=TestCA, O=Yubico, C=SE
        Fingerprint:    4a1416fce853429eaf420074bf8d39d72ff30bd84e4586f81ac2a19eda43fdf1
        Not Before:     Aug  8 14:29:23 2019 GMT
        Not After:      Aug  7 14:29:23 2021 GMT
        WARNING: Slot private key and certificate do not match
Slot 9e:
        Private Key Algorithm:      RSA2048
        Public Key Algorithm:       RSA2048
        Subject DN:     CN=card_auth, C=SE
        Issuer DN:      CN=TestCA, O=Yubico, C=SE
        Fingerprint:    803a89d5e196845d4a7e5e6006413fec1d30157128cfd9e3afe15010829226dd
        Not Before:     Aug  8 14:29:50 2019 GMT
        Not After:      Aug  7 14:29:50 2021 GMT
PIN tries left:     3

Example 2:

$ yubico-piv-tool -a status -s 9a
Version:    4.4.0
Serial Number:      12345678
CHUID:      No data available
CCC:        No data available
Slot 9a:
        Private Key Algorithm:      RSA2048
        Public Key Algorithm:       RSA2048
        Subject DN:     CN=piv_auth, C=SE
        Issuer DN:      CN=TestCA, O=Yubico, C=SE
        Fingerprint:    4a1416fce853b29eaf520174bf8639d72ff30bd84e4586f81ac2a19eda43fdf1
        Not Before:     Aug  8 14:29:23 2019 GMT
        Not After:      Aug  7 14:29:23 2021 GMT
PIN tries left:     3

Example 3:

$ yubico-piv-tool -a status -s f9
Version:    4.4.0
Serial Number:      12345678
CHUID:      3019d4e739da739ced39ce739d836858210842108421c84210c3eb3410461c7c766122b38b2edf05183c3d0
   41a350832303330303130313e00fe00
CCC:        f015a000000116ff02f9a5b5f5fc5cd67c63a147ddf405f10121f20121f300f40100f50110f600f700fa00f
   b00fc00fd00fe00
Slot f9:
    Private Key Algorithm:  RSA2048
    Public Key Algorithm:   RSA2048
    Subject DN: CN=Test Attestation Certificate
    Issuer DN:  CN=Test Attestation Certificate
    Fingerprint:        8dbc03bea80282748f0403de0922c93751fe498d376b6ae1aa87d1b8af74c7a3
    Not Before: Jan 22 09:47:58 2018 GMT
    Not After:  Jan 24 09:47:58 2018 GMT
PIN tries left:     3

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`

test-decipher

Syntax

$ yubico-piv-tool -a read-certificate -s <slot> [ -o cert.pem ]
$ yubico-piv-tool -a verify-pin -a test-decipher -s <slot> [ -P <PIN code> -i cert.pem ]

Description

Test the decryption function. This applies to both test-signature and test-decipher.

To test decryption:

Make sure there is a certificate stored on the slot being tested. To get the certificate, use the read-certificate action.
Verify the PIN code or the fingerprint, (for YubiKeys that support Bio verification). If the PIN code or fingerprint is not completed before a generation action, the tests fail.
- To verify the PIN, use -a verify-pin
- To verify the fingerprint, use -a verify-bio
Important

Run the test-decypher action before you run a generate action. If test is run out of order the test-decypher action fails.

Examples

Example 1:

$ yubico-piv-tool -a read-certificate -s 9a
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----

Example 2:

$ yubico-piv-tool -a verify-pin -a test-decipher -s 9a
Enter PIN:
Successfully verified PIN.
Please paste the certificate to encrypt for...
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
Successfully performed ECDH exchange with card.

Example 3:

It is also possible to combine the commands above into one single command. Be sure to use the correct actions order:

$ yubico-piv-tool -a read-certificate -a verify-pin -a test-decipher -s 9a -o cert.pem -i cert.pem
Enter PIN:
Successfully verified PIN.
Successfully performed ECDH exchange with card.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-P, --pin`	Optional	Pin/puk code for verification. If omitted, pin/puk is asked for.
`-i, --input`	Optional	Filename to use as input. If left out, input is read from `Stdin`.	`None` or file name Default: `Stdin`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`.	`None` or file name Default: `Stdout`

test-signature

Syntax

$ yubico-piv-tool -a read-certificate -s <slot> [ -o cert.pem ]
$ yubico-piv-tool -a verify-pin -a test-signature -s <slot> [ -P <PIN code> -i cert.pem ]

Description

Test the signature function. This applies to both test-signature and test-decipher.

To test signing:

Make sure there is a certificate stored on the slot being tested. To get the certificate, use the read-certificate action.
Verify the PIN code or the fingerprint, (for YubiKeys that support Bio verification). If the PIN code or fingerprint is not completed before a generation action, the tests fail.
- To verify the PIN, use -a verify-pin
- To verify the fingerprint, use -a verify-bio
Important

Run the test-decypher action before you run a generate action. If test is run out of order the test-signature action fails.

Examples

Example 1:

$ yubico-piv-tool -a read-certificate -s 9a
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----

Example 2:

$ yubico-piv-tool -a verify-pin -a test-signature -s 9a
Enter PIN:
Successfully verified PIN.
Please paste the certificate to verify against...
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
Successful ECDSA verification.

Example 3:

It is also possible to combine the commands above into one single command. Be sure to use the correct actions order:

$ yubico-piv-tool -a read-certificate -a verify-pin -a test-signature -s 9a -o cert.pem -i cert.pem
Enter PIN:
Successfully verified PIN.
Successful ECDSA verification.

Parameters

Parameter	Required Optional	Description	Possible values, Default
`-s, --slot`	Required	Key slot to operate on	`9a, 9c, 9d, 9e, 82, 83, 84,` `85, 86, 87,88, 89, 8a, 8b,` `8c, 8d, 8e, 8f, 90, 91, 92,` `93, 94, 95, f9` Default: `none`
`-P, --pin`	Optional	Pin/puk code for verification. If omitted, pin/puk is asked for.
`-i, --input`	Optional	Filename to use as input. If left out, input is read from `Stdin`.	`None` or file name Default: `Stdin`
`-o, --output`	Optional	Filename to use as output. If left out, output is printed to `Stdout`.	`None` or file name Default: `Stdout`

unblock-pin

No sample available.

verify-bio

Description

Use -a verify-pin to verify the PIN and -a verify-bio for fingerprint verification.

See generate, test-signature, test-decipher, or sign-data.

Examples

$ yubico-piv-tool -a verify-bio -a selfsign -s <slot> -S <subject dn> [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <public key file> --serial <cert serial number> --valid-days DAYS -o <cert file> ]

$ yubico-piv-tool -a verify-bio -a request-certificate -s <slot> -S <subject dn> [ -P <PIN> -i <public key file> -o <cert request file> ]

verify-pin

Description

Use -a verify-pin to verify the PIN and -a verify-bio for fingerprint verification.

See generate, test-signature, test-decipher, or sign-data.

Examples

$ yubico-piv-tool -a verify-pin -a selfsign -s <slot> -S <subject dn> [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <public key file> --serial <cert serial number> --valid-days DAYS -o <cert file> ]

$ yubico-piv-tool -a verify-pin -a request-certificate -s <slot> -S <subject dn> [ -P <PIN> -i <public key file> -o <cert request file> ]

version

Syntax

$ yubico-piv-tool -a version

Description

Displays the application version.

Examples

$ yubico-piv-tool -a version
Application version 4.4.0 found.

write-object

Syntax

$ yubico-piv-tool -a write-object --id <object ID> -k [ -i <input file>  -f <file format>]

Description

Writing an object is an action that requires authentication, which is done by providing the management key. If no management key is provided, the tool tries to authenticate using the default management key.

Important

It is strongly recommended to change the Yubikey’s PIN, PUK and management key before start using it.

See read-object for Supported PIV Object IDs for read- and write-object and parameters.