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.