yubico-piv-tool -a generate -s <slot> -k [ -A <key algorithm> -o <public key file> ] yubico-piv-tool -a verify-pin -a selfsign -s <slot> -S <subject dn> [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <public key file> --serial <cert serial number> --valid-days DAYS -o <cert file> ] yubico-piv-tool -a verify-pin -a request-certificate -s <slot> -S <subject dn> [ -P <PIN> -i <public key file> -o <cert request file> ] yubico-piv-tool -a import-certificate -s <slot> -k [ -o <cert file> ]
An occupied slot on the Yubikey PIV interface usually contains a private key, a public key and an X509 certificate. The key pair generate, the certificate generation and the certificate import are done using different actions in the right order.
Generating a key pair will have the public key as an output (action "generate"). The public key will be used to either generate a self signed certificate (action "selfsign") or a certificate request (action "request-certificate"). The resulting certificate should then be imported into the same slot (action "import-certificate").
Generating the key pair and importing the certificate are both actions that require
authentication, which is done by providing the management key. If no management key
is provided, the tool will try to authenticate using the default management key.
[It is strongly recommended to
change the Yubikey’s PIN, PUK and management key before start using it]
While generating the certificate/certificate request does not require authentication, the signing operation does
require verifying the PIN code or the fingerprint if the YubiKey supports Bio verification, which has to be done in an
action that must take place before the signing action, otherwise the operation will fail. Use -a verify-pin to
verify the PIN and -a verify-bio for fingerprint verification.
Parameter |
Required |
Optional |
Description |
Possible values |
Default value |
-s, --slot |
X |
What key slot to operate on |
9a, 9c, 9d, 9e, 82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 |
||
-k, --key |
X |
Management key to use, if no value is specified key will be asked for |
010203040506070801020304050607080102030405060708 |
||
-A, --algorithm |
X |
What algorithm to use to generate the key pair |
RSA1024, RSA2048, RSA3072 (Requires YubiKey 5.7 or higher), RSA4096 (Requires YubiKey 5.7 or higher), ECCP256, ECCP384, ED25519 (Requires YubiKey 5.7 or higher), X25519 (Requires YubiKey 5.7 or higher) |
RSA2048 |
|
-i, --input |
X |
Filename to use as input. If left out, input will be read from Stdin. The only supported format for public key is PEM |
None or file name |
Stdin |
|
-o, --output |
X |
Filename to use as output. If left out, output will be printed to Stdout |
None or file name |
Stdout |
|
-K, --key-format |
X |
Format of the certificate to import. Note that the public key must be in PEM format |
PEM, PKCS12, GZIP, DER |
PEM |
|
-S, --subject |
X |
The subject to use for the certificate. The subject must be written as: /CN=host.example.com/OU=test/O=example.com/ |
|||
-P, --pin |
X |
Pin/puk code for verification, if omitted pin/puk will be asked for |
|||
--pin-policy |
Set pin policy applicable for the slot containing the key. Only available on YubiKey 4 or newer |
never, once, always, matchonce (applicable with bio verification), matchalways (applicable for with verification) |
|
||
--touch-policy |
Set touch policy applicable for the slot containing the key. Only available on YubiKey 4 or newer |
never, always, caches |
never |
||
--serial |
X |
Serial number of the self-signed certificate |
|||
--valid-days |
X |
Time (in days) until the self-signed certificate expires |
365 |
yubico-piv-tool -a generate -s 9a -A ECCP256 -k -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwyLPuYF7xF4iQ+5VWUnDQsMSf9O7 Jc1gBDHQJ0kfYnZ8tV2OFk3JFyfZDL9g9g3eFaH00dzstxH7te64DtYepw== -----END PUBLIC KEY----- Successfully generated a new private key.
yubico-piv-tool -a verify-pin -a selfsign -s 9a -S '/CN=piv_auth/OU=test/O=example.com/' Enter PIN: Successfully verified PIN. Please paste the public key... -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwyLPuYF7xF4iQ+5VWUnDQsMSf9O7 Jc1gBDHQJ0kfYnZ8tV2OFk3JFyfZDL9g9g3eFaH00dzstxH7te64DtYepw== -----END PUBLIC KEY----- -----BEGIN CERTIFICATE----- MIIBujCCAWCgAwIBAgIJAJKWdUFfuvqiMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe Fw0xOTA4MTIxMzM0NTdaFw0yMDA4MTExMzM0NTdaMDgxETAPBgNVBAMMCHBpdl9h dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG SM49AgEGCCqGSM49AwEHA0IABMMiz7mBe8ReIkPuVVlJw0LDEn/TuyXNYAQx0CdJ H2J2fLVdjhZNyRcn2Qy/YPYN3hWh9NHc7LcR+7XuuA7WHqejUzBRMB0GA1UdDgQW BBQS0iNbyP8W817uCk/2lPd19ZvNRDAfBgNVHSMEGDAWgBQS0iNbyP8W817uCk/2 lPd19ZvNRDAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQC5CTvl LE0htwa89LBRRSL2BWHqciSLvqx9azjJfd63JAIgcAJSIhWpiXeBcGZdcTbnmkqU kWu4LDU2ymBRp8pp4Iw= -----END CERTIFICATE----- Successfully generated a new self signed certificate.
yubico-piv-tool -a import-certificate -s 9a -k Please paste the certificate... -----BEGIN CERTIFICATE----- MIIBujCCAWCgAwIBAgIJAJKWdUFfuvqiMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe Fw0xOTA4MTIxMzM0NTdaFw0yMDA4MTExMzM0NTdaMDgxETAPBgNVBAMMCHBpdl9h dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG SM49AgEGCCqGSM49AwEHA0IABMMiz7mBe8ReIkPuVVlJw0LDEn/TuyXNYAQx0CdJ H2J2fLVdjhZNyRcn2Qy/YPYN3hWh9NHc7LcR+7XuuA7WHqejUzBRMB0GA1UdDgQW BBQS0iNbyP8W817uCk/2lPd19ZvNRDAfBgNVHSMEGDAWgBQS0iNbyP8W817uCk/2 lPd19ZvNRDAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQC5CTvl LE0htwa89LBRRSL2BWHqciSLvqx9azjJfd63JAIgcAJSIhWpiXeBcGZdcTbnmkqU kWu4LDU2ymBRp8pp4Iw= -----END CERTIFICATE----- Successfully imported a new certificate.
It is also possible to combine all these commands above into one single command (notice the order of the actions):
yubico-piv-tool -a generate -a verify-pin -a selfsign -a import-certificate -s 9a -k -A ECCP256 -S '/CN=piv_auth/OU=test/O=example.com/'
yubico-piv-tool -a generate -s 9c -A RSA2048 -o pub.key Successfully generated a new private key.
yubico-piv-tool -a verify-pin -a request-certificate -s 9c -S '/CN=digi_sign/OU=test/O=example.com/' -i pub.key -o csr.pem Enter PIN: Successfully verified PIN. Successfully generated a certificate request.
After sending the certificate request to the CA and getting a signed certificate:
yubico-piv-tool -a import-certificate -s 9c -i cert.pem Successfully imported a new certificate.