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
'-' 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
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 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. |
-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
'-' touse
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
'-' 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 ] |
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
- 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
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 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. |
--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
'-' 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. |
-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.