PIV Commands
Acronyms and their definitions are listed at the bottom of the Base Commands page.
ykman piv [OPTIONS] COMMAND [ARGS]…
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]…
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 the PUK). |
ykman piv access change-management-key [OPTIONS]
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.
With the release of the 5.7 YubiKey firmware version, Advanced Encryption Standard 192 bit (AES-192) is the default security type for the PIV Management Key. Triple Data Encryption Standard (TDES or 3DES) is the default security type for YubiKey firmware versions older than 5.7.
The default value is the same for all firmware versions, regardless of the security type. For this value as well as the default PIN and PUK codes, see the “General Information” section of “Yubico PIV Tool” on our developer site.
Options
| Option | Description |
|---|---|
-h, --help |
Show this message and exit. |
-a, --algorithm [TDES/3DES|AES128|AES192|AES256] |
Management key algorithm.
[Default v5.7:
AES-192][Default pre-v.5.7:
TDES] |
-f, --force |
Confirm the action without prompting. |
-g, --generate |
Generate a random management key.
Implied by
--protect unless--new-management-key is alsogiven. Conflicts with
--new-management-key. |
-m, --management-key TEXT |
Current management key (TEXT = identifier). |
-n, --new-management-key TEXT |
A new management key (TEXT = identifer). |
-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]
Change the PIN code. The PIN must be between 6 and 8 alphanumeric characters. 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]
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
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 (TEXT = identifier). |
-P, --pin TEXT |
PIN code. |
ykman piv access unblock-pin [OPTIONS]
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]…
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
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 (TEXT = identifier) |
-P, --pin TEXT |
PIN code. |
ykman piv certificates export [OPTIONS] SLOT CERTIFICATE
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
'-' touse
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
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 usestdin. |
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 (TEXT = identifier) |
-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
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
'-' touse
stdin. |
Options
| Option | Description |
|---|---|
-h, --help |
Show this message and exit. |
-m, --management-key TEXT |
The management key (TEXT = identifier). |
-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
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 usestdin. |
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]
Display general status of PIV application.
Options
| Option | Description |
|---|---|
-h, --help |
Show this message and exit. |
ykman piv keys [OPTIONS] COMMAND [ARGS]…
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
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
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
- touse
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
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 [RSA1024RSA2048|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 (TEXT = identifier). |
-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
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 usestdin. |
SLOT |
PIV slot of the private key. |
Options
| Option | Description |
|---|---|
-h, --help |
Show this message and exit. |
-m, --management-key TEXT |
The management key (TEXT = identifier). |
--pin-policy [DEFAULT|NEVERONCE|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]…
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
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
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 (TEXT = identifier). |
-P, --pin TEXT |
PIN code. |
ykman piv objects import [OPTIONS] OBJECT DATA
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
'-' touse
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 (TEXT = identifier). |
-P, --pin TEXT |
PIN code. |
ykman piv reset [OPTIONS]
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. |
Click for Yubico Support.