PIV Commands

Acronyms and their definitions are listed at the bottom of the Base Commands page.

ykman piv [OPTIONS] COMMAND [ARGS]…

Description:	Manage the PIV Application.

Examples

Generate an ECC P-256 private key and a self-signed certificate in slot 9a:

$ ykman piv keys generate --algorithm ECCP256 9a pubkey.pem
$ ykman piv certificates generate --subject "yubico" 9a pubkey.pem

Change the PIN from 123456 to 654321:

$ ykman piv access change-pin --pin 123456 --new-pin 654321

Reset all PIV data and restore default settings:

$ ykman piv reset

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`access`	Manage PIN, PUK and Management Key.
`certificates`	Manage certificates.
`info`	Display general status of the PIV application.
`keys`	Manage private keys.
`objects`	Manage PIV data objects.
`reset`	Reset all PIV data.

ykman piv access [OPTIONS] COMMAND [ARGS]…

Description:	Manage PIN, PUK, and Management Key.

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`change-management-key`	Change the management key.
`change-pin`	Change the PIN code.
`change-puk`	Change the PUK code.
`set-retries`	Set the number of PIN and PUK retry attempts.
`unblock-pin`	Unblock the PIN (using PUK).

ykman piv access change-management-key [OPTIONS]

Description:	Change the management key. Management functionality is guarded by a management key. This key is required for administrative tasks, such as generating key pairs. A random key may be generated and stored on the YubiKey, protected by PIN.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-a, --algorithm [TDES\|` `AES128\|AES192\|AES256]`	Management key algorithm. [Default: `TDES`]
`-f, --force`	Confirm the action without prompting.
`-g, --generate`	Generate a random management key. Implied by `--protect` unless `--new-management-key` is also given. Conflicts with `--new-management-key`.
`-m, --management-key TEXT`	Current management key.
`-n, --new-management-key TEXT`	A new management key.
`-p, --protect`	Store new management key on the YubiKey, protected by PIN. A random key is used if no key is provided.
`-P, --pin TEXT`	PIN code.
`-t, --touch`	Require touch on YubiKey when prompted for management key.

ykman piv access change-pin [OPTIONS]

Description:	Change the PIN code. The PIN must be between 6 and 8 characters long, and it can be any type of alphanumeric character. For cross-platform compatibility, numeric PINs are recommended.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-n, --new-pin TEXT`	A new PIN.
`-P, --pin TEXT`	Current PIN code.

ykman piv access change-puk [OPTIONS]

Description:	Change the PUK code. If the PIN is lost or blocked it can be reset using a PUK. The PUK must be between 6 and 8 characters long, and it can be any type of alphanumeric character.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-n, --new-puk TEXT`	A new PUK code.
`-p, --puk TEXT`	Current PUK code.

ykman piv access set-retries [OPTIONS] PIN-RETRIES PUK-RETRIES

Description:	Set the number of PIN and PUK retry attempts.

Note

This resets the PIN and PUK to their factory defaults.

Arguments

Argument	Description
`PIN-RETRIES`	Set number of retries for PIN attempts.
`PUK-RETRIES`	Set number of retries for PUK attempts.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-f, --force`	Confirm the action without prompting.
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.

ykman piv access unblock-pin [OPTIONS]

Description:	Unblock the PIN (using PUK).

Options

Option	Description
`-h, --help`	Show this message and exit.
`-n, --new-pin NEW-PIN`	A new PIN code.
`-p, --puk TEXT`	Current PUK code.

ykman piv certificates [OPTIONS] COMMAND [ARGS]…

Description:	Manage certificates.

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Option	Description
`delete`	Delete a certificate.
`export`	Export an X.509 certificate.
`generate`	Generate a self-signed X.509 certificate.
`import`	Import an X.509 certificate.
`request`	Generate a Certificate Signing Request (CSR).

ykman piv certificates delete [OPTIONS] SLOT

Description:	Delete a certificate. Delete a certificate from a PIV slot on the YubiKey.

Arguments

Argument	Description
`SLOT`	PIV slot of the certificate.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.

ykman piv certificates export [OPTIONS] SLOT CERTIFICATE

Description:	Export an X.509 certificate. Reads a certificate from one of the PIV slots on the YubiKey.

Arguments

Argument	Description
`SLOT`	PIV slot of the certificate.
`CERTIFICATE`	File to write certificate to. Use `'-'` to use `stdout`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-F, --format [PEM\|DER]`	Encoding format. [Default: `PEM`]

ykman piv certificates generate [OPTIONS] SLOT PUBLIC-KEY

Description:	Generate a self-signed X.509 certificate. A self-signed certificate is generated and written to one of the slots on the YubiKey. A private key must already be present in the corresponding key slot.

Arguments

Argument	Description
`SLOT`	PIV slot of the certificate.
`PUBLIC-KEY`	File containing a public key. Use `'-'` to use `stdin`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-a, --hash-algorithm` `[SHA1\|SHA256\|SHA384\|SHA512]`	Hash algorithm. [default: SHA256]
`-d, --valid-days INTEGER`	Number of days until the certificate expires. [Default: `365`]
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.
`-s, --subject TEXT`	Subject for the certificate, as an RFC 4514 string. [required].

ykman piv certificates import [OPTIONS] SLOT CERTIFICATE

Description:	Import an X.509 certificate. Write a certificate to one of the PIV slots on the YubiKey.

Arguments

Argument	Description
`SLOT`	PIV slot of the certificate.
`CERTIFICATE`	File containing the certificate. Use `'-'` to use `stdin`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-key TEXT`	The management key.
`-p, --password TEXT`	A password may be needed to decrypt the data.
`-P, --pin TEXT`	PIN code.
`-v, --verify`	Verify that the certificate matches the private key in the slot.

ykman piv certificates request [OPTIONS] SLOT PUBLIC-KEY CSR

Description:	Generate a Certificate Signing Request (CSR). A private key must already be present in the corresponding key slot.

Arguments

Argument	Description
`CSR`	File to write CSR to. Use `'-'` to use `stdout`.
`PUBLIC-KEY`	File containing a public key. Use `'-'` to use `stdin`.
`SLOT`	PIV slot of the certificate.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-a, --hash-algorithm` `[SHA1\|SHA256\|SHA384\|SHA512]`	Hash algorithm. [default: SHA256]
`-P, --pin TEXT`	PIN code.
`-s, --subject TEXT`	Subject for the requested certificate, as an RFC 4514 string. [Required]

ykman piv info [OPTIONS]

Description:	Display general status of PIV application.

Options

Option	Description
`-h, --help`	Show this message and exit.

ykman piv keys [OPTIONS] COMMAND [ARGS]…

Description:	Manage private keys.

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`attest`	Generate an attestation certificate for a key pair.
`export`	Export a public key corresponding to a stored private key.
`generate`	Generate an asymmetric key pair.
`import`	Import a private key from file.

ykman piv keys attest [OPTIONS] SLOT CERTIFICATE

Description:	Generate an attestation certificate for a key pair. Attestation is used to show that an asymmetric key was generated on the YubiKey and therefore doesn’t exist outside the device.

Arguments

Argument	Description
`CERTIFICATE`	File to write attestation certificate to. Use `'-'` to use `stdout`.
`SLOT`	PIV slot of the private key.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-F, --format [PEM\|DER]`	Encoding format. [Default: `PEM`]

ykman piv keys export [OPTIONS] SLOT PUBLIC-KEY

Description: Export a public key corresponding to a stored private key. This command uses several different mechanisms for exporting the public key corresponding to a stored private key, which may fail. If a certificate is stored in the slot it is assumed to contain the correct public key. If this is not the case, the wrong public key will be returned. The --verify flag can be used to verify that the public key being returned matches the private key, by using the slot to create and verify a signature. This may require the PIN to be provided.

Arguments

Argument	Description
`PUBLIC-KEY`	File containing the generated public key. Use `-` to use `stdout`.
`SLOT`	PIV slot of the private key.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-F, --format [PEM\|DER]`	Encoding format. [default: `PEM`]
`-P, --pin TEXT`	PIN code (used for `--verify`).
`-v, --verify`	Verify that the public key matches the private key in the slot.

ykman piv keys generate [OPTIONS] SLOT PUBLIC-KEY

Description: Generate an asymmetric key pair. The private key is generated on the YubiKey, and written to one of the slots.

Arguments

Argument	Description
`PUBLIC-KEY`	File containing the generated public key. Use `'-'` to use `stdout`.
`SLOT`	PIV slot of the private key.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-a, --algorithm [RSA1024` `RSA2048\|ECCP256\|ECCP384]`	Algorithm to use in key generation. [Default: `RSA2048`]
`-F, --format [PEM\|DER]`	Encoding format. [Default: `PEM`]
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.
`--pin-policy [DEFAULT\|` `NEVER\|ONCE\|ALWAYS]`	PIN policy for slot.
`--touch-policy [DEFAULT\|` `NEVER\|ALWAYS\|CACHED]`	Touch policy for slot.

ykman piv keys import [OPTIONS] SLOT PRIVATE-KEY

Description:	Import a private key from file. Write a private key to one of the PIV slots on the YubiKey.

Arguments

Argument	Description
`PRIVATE-KEY`	File containing the private key. Use `'-'` to use `stdin`.
`SLOT`	PIV slot of the private key.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-key TEXT`	The management key.
`--pin-policy [DEFAULT\|NEVER` `ONCE\|ALWAYS]`	PIN policy for slot.
`-p, --password TEXT`	Password used to decrypt the private key.
`-P, --pin TEXT`	PIN code.
`--touch-policy [DEFAULT\|` `NEVER\|ALWAYS\|CACHED]`	Touch policy for slot.

ykman piv objects [OPTIONS] COMMAND [ARGS]…

Description:	Manage PIV data objects.

Examples

Write the contents of a file to data object with ID: abc123:

$ ykman piv objects import abc123 myfile.txt

Read the contents of the data object with ID: abc123 into a file:

$ ykman piv objects export abc123 myfile.txt

Generate a random value for CHUID:

$ ykman piv objects generate chuid

Options

Option	Description
`-h, --help`	Show this message and exit.

Commands

Command	Description
`export`	Export an arbitrary PIV data object.
`generate`	Generate and write data for a supported data object.
`import`	Write an arbitrary PIV object.

ykman piv objects export [OPTIONS] OBJECT OUTPUT

Description:	Export an arbitrary PIV data object.

Arguments

Argument	Description
`OBJECT`	Name of PIV data object, or ID in HEX.
`OUTPUT`	File to write object to. Use `'-'` to use `stdout`.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-P, --pin TEXT`	PIN code.

ykman piv objects generate [OPTIONS] OBJECT

Description:	Generate and write data for a supported data object.

Arguments

Argument	Description
`OBJECT`	Name of PIV data object, or ID in HEX. Supported data objects are: `CHUID` (Card Holder Unique ID) `CCC` (Card Capability Container)

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.

ykman piv objects import [OPTIONS] OBJECT DATA

Description:	Write an arbitrary PIV object. Write a PIV object by providing the object id. Yubico writable PIV objects are available in the range 5f0000 - 5fffff.

Arguments

Argument	Description
`DATA`	File containing the data to be written. Use `'-'` to use `stdin`.
`OBJECT`	Name of PIV data object, or ID in HEX.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-m, --management-key TEXT`	The management key.
`-P, --pin TEXT`	PIN code.

ykman piv reset [OPTIONS]

Description:	Reset all PIV data. This action wipes all data and restores factory settings for the PIV application on your YubiKey.

Options

Option	Description
`-h, --help`	Show this message and exit.
`-f, --force`	Confirm the action without prompting.

To get in touch with Yubico Support, click here.