PIV Commands

Acronyms and their definitions are listed at the bottom of this 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

  • -h, --help Show this message and exit.

Commands

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

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

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

ykman piv access change-pin [OPTIONS]

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

Options

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

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 supports any type of alphanumeric characters.

Options

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

ykman piv certificates delete [OPTIONS] SLOT

Description:

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

SLOT PIV slot of the certificate.

Options

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

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.

SLOT PIV slot of the certificate.

CERTIFICATE File to write certificate to. Use '-' to use stdout.

Options

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

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.

SLOT PIV slot of the certificate.

PUBLIC-KEY File containing a public key. Use ‘-‘ to use stdin.

Options

  • -m, --management-key TEXT The management key.
  • -P, --pin TEXT PIN code.
  • -s, --subject TEXT Subject common name (CN) for the certificate [required].
  • -d, --valid-days INTEGER Number of days until the certificate expires. [Default: 365]
  • -h, --help Show this message and exit.

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.

SLOT PIV slot of the certificate.

PUBLIC-KEY File containing a public key. Use '-' to use stdin.

CSR File to write CSR to. Use '-' to use stdout.

Options

  • -P, --pin TEXT PIN code.
  • -s, --subject TEXT Subject common name (CN) for the requested certificate. [Required]
  • -h, --help Show this message and exit.

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.

SLOT PIV slot of the private key.

PUBLIC-KEY File containing the generated public key. Use '-' to use stdout.

Options

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

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.

SLOT PIV slot of the certificate.

CERTIFICAT File containing the certificate. Use ‘-‘ to use stdin.

Options

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

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.

SLOT PIV slot of the private key.

PRIVATE-KEY File containing the private key. Use '-' to use stdin.

Options

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

ykman piv info [OPTIONS]

Description:Display general status of PIV application.

Options

  • -h, --help Show this message and exit.

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.

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

Options

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

ykman piv objects export [OPTIONS] OBJECT OUTPUT

Description:

Export an arbitrary PIV data object.

OBJECT Name of PIV data object, or ID in HEX.

OUTPUT File to write object to. Use '-' to use stdout.

Options

  • -P, --pin TEXT PIN code.
  • -h, --help Show this message and exit.

ykman piv reset [OPTIONS]

Description:Reset all PIV data. This action will wipe all data and restore factory settings for the PIV application on your YubiKey.

Options

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

ykman piv objects generate [OPTIONS] OBJECT

Description:

Generate and write data for a supported data object.

OBJECT Name of PIV data object, or ID in HEX.

Supported data objects are:

  • “CHUID” (Card Holder Unique ID)
  • “CCC” (Card Capability Container)

Options

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

ykman piv objects generate [OPTIONS] OBJECT

Description:

Generate and write data for a supported data object.

OBJECT Name of PIV data object, or ID in HEX.

Supported data objects are:

“CHUID” (Card Holder Unique ID)

“CCC” (Card Capability Container)

Options

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

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

Description:

Set the number of PIN and PUK retry attempts.

Note

This will reset the PIN and PUK to their factory defaults.

Options

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

ykman piv access unblock-pin [OPTIONS]

Description:Unblock the PIN (using PUK).

Options

  • -p, --puk TEXT
  • -n, --new-pin NEW-PIN
  • -h, --help Show this message and exit.

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.

OBJECT Name of PIV data object, or ID in HEX.

DATA File containing the data to be written. Use '-' to use stdin.

Options

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

Acronyms

3DES:Triple Data Encryption Algorithm
AES:Advanced Encryption Standard
CCC:Card Capability Container
CCID:Chip card interface device, a USB protocol for a smartcard.
CHUID:Card Holder Unique ID
CN:Common name
CSR:Certificate Signing Request
ECC:Elliptic curve cryptography
FIDO:Fast Identity Online
FIPS:Federal Information Processing Standards (US government) covering codes and encryption standards.
HMAC:Hash-based message authentication code
HOTP:HMAC-based One-Time Password algorithm
OATH:The Initiative for Open Authentication is an organization that specifies two open authentication standards, TOTP and HOTP
OTP:One-Time Password
PUK:PIN Unlock Key
stdin:standard input - usually keyboard or CLI instructions
stdout:standard output - usually print to screen
TOTP:Time-based One-Time Password algorithm
X.509:The standard defining the format of a public key certificate

To get in touch with Yubico Support, go to https://support.yubico.com/hc/en-us/requests/new.