Yubico PIV Tool

https://github.com/yubico/yubico-piv-tool
Admin
Yubico PIV Tool is a command-line utility and shared library for managing cryptographic keys and...
Tokens:38,461
Snippets:286
Trust Score:9.4
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Read Certificate Example

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/test-signature.adoc

Example output of reading a certificate from slot 9a.

```bash
$ yubico-piv-tool -a read-certificate -s 9a
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
```

--------------------------------

### Read Certificate Example

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/read_certificate.adoc

Example command and output for reading a certificate from slot 9a.

```bash
$ yubico-piv-tool -a read-cert -s 9a
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
```

--------------------------------

### Check Yubico PIV Tool Help

Source: https://github.com/yubico/yubico-piv-tool/blob/master/vagrant/development/README.md

Verify the installation by displaying the help message for the yubico-piv-tool.

```bash
ubuntu@ubuntu-xenial $ yubico-piv-tool --help
```

--------------------------------

### Build and Install Yubico PIV Tool

Source: https://github.com/yubico/yubico-piv-tool/blob/master/vagrant/development/README.md

Commands to navigate to the project directory within the VM, create a build directory, configure with CMake, build, and install the tool.

```bash
ubuntu@ubuntu-xenial $ cd /vagrant
ubuntu@ubuntu-xenial $ mkdir build; cd build
ubuntu@ubuntu-xenial $ cmake ..
ubuntu@ubuntu-xenial $ make
ubuntu@ubuntu-xenial $ sudo make install
```

--------------------------------

### Start and SSH into Vagrant VM

Source: https://github.com/yubico/yubico-piv-tool/blob/master/vagrant/development/README.md

Use these commands to start the Vagrant development environment and access the virtual machine via SSH.

```bash
alice@work $ cd yubico-piv-tool/vagrant/development
alice@work $ vagrant up
alice@work $ vagrant ssh
```

--------------------------------

### Move Key Example

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_move.adoc

Example command moving a key from slot 9c to slot 84.

```bash
$ yubico-piv-tool -a move-key -s 9c --to-slot 84 -k
Enter Password:
Enter management key:
Successfully moved key.
```

--------------------------------

### Verify PIN and Test Signature Example

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/test-signature.adoc

Example output of verifying a PIN and performing a signature test on slot 9a.

```bash
$ yubico-piv-tool -a verify-pin -a test-signature -s 9a
Enter PIN:
Successfully verified PIN.
Please paste the certificate to verify against...
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
Successful ECDSA verification.
```

--------------------------------

### Combined Signature Test Command

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/test-signature.adoc

Example of combining certificate reading, PIN verification, and signature testing into a single command.

```bash
$ yubico-piv-tool -a read-certificate -a verify-pin -a test-signature -s 9a -o cert.pem -i cert.pem
Enter PIN:
Successfully verified PIN.
Successful ECDSA verification.
```

--------------------------------

### Initialize and Connect with libykpiv

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Initialize the library state and establish a connection to the YubiKey device.

```c
#include <ykpiv/ykpiv.h>

int main() {
    ykpiv_state *state = NULL;
    ykpiv_rc rc;

    // Initialize library with verbose output
    rc = ykpiv_init(&state, 1);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Failed to init: %s\n", ykpiv_strerror(rc));
        return 1;
    }

    // Connect to YubiKey (NULL uses first available)
    rc = ykpiv_connect(state, NULL);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Failed to connect: %s\n", ykpiv_strerror(rc));
        ykpiv_done(state);
        return 1;
    }

    // Get device version
    char version[16];
    rc = ykpiv_get_version(state, version, sizeof(version));
    if (rc == YKPIV_OK) {
        printf("YubiKey version: %s\n", version);
    }

    // Get serial number
    uint32_t serial;
    rc = ykpiv_get_serial(state, &serial);
    if (rc == YKPIV_OK) {
        printf("Serial: %u\n", serial);
    }

    // Disconnect and cleanup
    ykpiv_disconnect(state);
    ykpiv_done(state);
    return 0;
}
```

--------------------------------

### Initialize and Connect (libykpiv C API)

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Initialize the library state and connect to a YubiKey device using the C library.

```APIDOC
## libykpiv C Library API

### Initialize and Connect

Initialize the library state and connect to a YubiKey device.

```c
#include <ykpiv/ykpiv.h>

int main() {
    ykpiv_state *state = NULL;
    ykpiv_rc rc;

    // Initialize library with verbose output
    rc = ykpiv_init(&state, 1);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Failed to init: %s\n", ykpiv_strerror(rc));
        return 1;
    }

    // Connect to YubiKey (NULL uses first available)
    rc = ykpiv_connect(state, NULL);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Failed to connect: %s\n", ykpiv_strerror(rc));
        ykpiv_done(state);
        return 1;
    }

    // Get device version
    char version[16];
    rc = ykpiv_get_version(state, version, sizeof(version));
    if (rc == YKPIV_OK) {
        printf("YubiKey version: %s\n", version);
    }

    // Get serial number
    uint32_t serial;
    rc = ykpiv_get_serial(state, &serial);
    if (rc == YKPIV_OK) {
        printf("Serial: %u\n", serial);
    }

    // Disconnect and cleanup
    ykpiv_disconnect(state);
    ykpiv_done(state);
    return 0;
}
```
```

--------------------------------

### Import Key and Certificate Command Syntax

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Demonstrates the command-line syntax for importing both a private key and a certificate into the same YubiKey PIV slot. This combined operation requires the slot, management key, and allows for optional parameters related to PIN policy, touch policy, input file, and its format.

```bash
$ yubico-piv-tool -a import-key -a import-certificate -s <slot> -k [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <input file> -p <input file password> -K <input file format> ]
```

--------------------------------

### GET Status

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/status.adoc

Displays the device's meta data and the content of slots 9a, 9c, 9d, and 9e. Optionally displays slot f9 if specified.

```APIDOC
## GET status

### Description
Displays the device's meta data and the content of slots 9a, 9c, 9d and 9e. The content of slot f9 will be displayed if the slot is specified as an argument.

### Method
GET

### Endpoint
yubico-piv-tool -a status

### Parameters
#### Query Parameters
- **-s, --slot** (string) - Optional - What key slot to operate on. Possible values: 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

### Response
#### Success Response (200)
- **Version** (string) - Device version
- **Serial Number** (string) - Device serial number
- **Slot Content** (object) - Details of the requested slot including algorithm, DN, and fingerprint
- **PIN tries left** (integer) - Number of remaining PIN attempts
```

--------------------------------

### Generate ECC-P256 Key and Print Public Key

Source: https://github.com/yubico/yubico-piv-tool/blob/master/README.adoc

Generates a new ECC-P256 key on a YubiKey in slot 9a and prints the corresponding public key to standard output. Requires the yubico-piv-tool to be installed and accessible in the system's PATH.

```bash
yubico-piv-tool -s9a -AECCP256 -agenerate
```

--------------------------------

### Build Yubico PIV Tool on Windows with vcpkg

Source: https://github.com/yubico/yubico-piv-tool/blob/master/README.adoc

Set environment variables for OpenSSL and create build directories. Specify architecture and paths for GETOPT library and include directories when configuring with CMake. Build the project using CMake.

```powershell
$ env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR"
$ mkdir build; cd build
$ cmake -A <ARCH> -DGETOPT_LIB_DIR="PATH/TO/GETOPT_DIR/lib" -DGETOPT_INCLUDE_DIR="PATH/TO/GETOPT_DIR/include ..
$ cmake --build .
```

--------------------------------

### Configure SunPKCS11 Provider

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/Java_keytool.adoc

Create a configuration file to define the YKCS11 library path for the SunPKCS11 provider.

```bash
name = ykcs11
library = /path/to/libykcs11.so
```

--------------------------------

### Import Key Command Syntax

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Illustrates the command-line syntax for importing a private key into a YubiKey PIV slot. Optional parameters allow specifying PIN policy, touch policy, input file, and its password and format.

```bash
$ yubico-piv-tool -a import-key -s <slot> -k [ -P <PIN code> --pin-policy <never|once|always|matchonce|matchalways> --touch-policy <never|always|cached> -i <input file> -p <input file password> -K <input file format> ]
```

--------------------------------

### List Keystore Content

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/Java_keytool.adoc

Use keytool to list keys stored on the YubiKey PIV via the PKCS#11 interface.

```bash
$ keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /path/to/sun_ykcs11.conf
```

--------------------------------

### Build and Test Yubico PIV Tool on Windows with vcpkg

Source: https://github.com/yubico/yubico-piv-tool/blob/master/README.adoc

Set environment variables for OpenSSL and create build directories. Specify architecture, paths for GETOPT library and include directories, and the path to the 'check' test suite when configuring with CMake. Build the project. Add necessary directories to the PATH environment variable and run tests using ctest.

```powershell
$ env:OPENSSL_ROOT_DIR ="PATH/TO/OPENSSL_DIR"
$ mkdir build; cd build
$ cmake -A <ARCH> -DGETOPT_LIB_DIR="PATH/TO/GETOPT_DIR/lib" -DGETOPT_INCLUDE_DIR="PATH/TO/GETOPT_DIR/include -DCHECK_PATH="PATH/TO/CHECK_DIR" ..
$ cmake --build .
$ $env:Path += ";PATH/TO//CHECK_DIR/bin;PATH/TO/OPENSSL_DIR/bin;PATH/TO/build\lib\Debug;PATH/TO/build\ykcs11/Debug"
$ ctest.exe -C Debug
```

--------------------------------

### Import Certificate Command Syntax

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Shows the command-line syntax for importing a certificate into a YubiKey PIV slot. Requires specifying the slot and management key, with optional input file and format parameters.

```bash
$ yubico-piv-tool -a import-certificate -s <slot> -k [ -i <input file> -K <input file format> ]
```

--------------------------------

### Configure Firefox for YubiKey

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Steps to load the PKCS#11 module into Firefox for client certificate authentication.

```text
Firefox Configuration:
1. Open Settings → Privacy & Security → Security Devices
2. Click "Load" and provide:
   - Module Name: YubiKey
   - Module filename: /usr/local/lib/libykcs11.so (Linux/macOS)
                      C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll (Windows)
3. Click OK to load the module
4. The YubiKey certificates will appear in Certificate Manager
```

--------------------------------

### Perform PKCS#11 Operations with pkcs11-tool

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Common operations for listing slots, objects, and signing data using the OpenSC pkcs11-tool.

```bash
# List available slots
$ pkcs11-tool --module /usr/local/lib/libykcs11.so --list-slots
Available slots:
Slot 0 (0x0): Yubico YubiKey
  token state:   uninitialized

# List objects on the token
$ pkcs11-tool --module /usr/local/lib/libykcs11.so --list-objects --login
Using slot 0 with a present token (0x0)
Logging in to "YubiKey PIV #12345678".
Please enter User PIN:
Private Key Object; RSA
  label:      Private key for PIV Authentication
  ID:         01
  Usage:      decrypt, sign
Certificate Object; type = X.509 cert
  label:      X.509 Certificate for PIV Authentication
  ID:         01

# Sign data using PKCS#11
$ pkcs11-tool --module /usr/local/lib/libykcs11.so \
    --sign --mechanism SHA256-RSA-PKCS \
    --id 01 --login --input-file data.txt --output-file signature.bin
```

--------------------------------

### Import Key and Certificate

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Imports external keys and certificates into PIV slots using various formats.

```bash
# Import key and certificate from PKCS#12 file
$ yubico-piv-tool -a import-key -a import-certificate -s 9c -i credentials.pfx -K PKCS12 -k
Enter Password:
Enter management key:
Successfully imported a new private key.
Successfully imported a new certificate.

# Import certificate only (PEM format)
$ yubico-piv-tool -a import-certificate -s 9a -i certificate.pem -k
Successfully imported a new certificate.

# Import large certificate with compression
$ yubico-piv-tool -a import-certificate -s 9c -i large_cert.gz -K GZIP -k
Successfully imported a new certificate.

# Import key with custom PIN and touch policies
$ yubico-piv-tool -a import-key -s 85 -i private.pem \
    --pin-policy=always --touch-policy=always -k
Successfully imported a new private key.
```

--------------------------------

### Sign and Verify JAR Files

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/Java_keytool.adoc

Commands for signing a JAR file using a YubiKey PIV slot and verifying the signature, including debug options.

```bash
$ jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /path/to/sun_ykcs11.conf lib.jar "X.509 Certificate for Digital Signature"
```

```bash
jarsigner -verify -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /path/to/sun_ykcs11.conf lib.jar "X.509 Certificate for Digital Signature" -J-Djava.security.debug=sunpkcs11
```

```bash
$ jarsigner -verify -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /path/to/sun_ykcs11.conf lib.jar "X.509 Certificate for Digital Signature" 
```

--------------------------------

### Import Key and Certificate

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Imports both a private key and its corresponding certificate into a specified slot. Requires management key authentication. The tool will prompt for the password if the input file is encrypted and for the management key.

```bash
$ yubico-piv-tool -a import-key -a import-certificate -s 9c -k -i key.pfx -K PKCS12
Enter Password:
Enter management key:
Successfully imported a new private key.
Successfully imported a new certificate.
```

--------------------------------

### Import Key, Certificate, and Set CHUID

Source: https://github.com/yubico/yubico-piv-tool/blob/master/README.adoc

Sets a random CHUID, imports a private key from a PKCS12 file, and imports a certificate into slot 9c. This operation requires the path to the PKCS12 file and may prompt for passwords.

```bash
yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key \
    -aimport-cert
```

--------------------------------

### Integrate YubiKey with Java Keytool

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Configuration and commands for using YubiKey with Java applications via the SunPKCS11 provider.

```bash
# Create PKCS#11 configuration file (yubikey.cfg)
$ cat > yubikey.cfg << EOF
name = YubiKey
library = /usr/local/lib/libykcs11.so
slot = 0
EOF

# List certificates from YubiKey
$ keytool -list -keystore NONE -storetype PKCS11 \
    -providerClass sun.security.pkcs11.SunPKCS11 \
    -providerArg yubikey.cfg
Enter keystore password: (PIN)
Keystore type: PKCS11
Keystore provider: SunPKCS11-YubiKey

Your keystore contains 1 entry

Private key for PIV Authentication, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 4A:14:16:FC:E8:53:B2:9E:...

# Sign JAR file with YubiKey
$ jarsigner -keystore NONE -storetype PKCS11 \
    -providerClass sun.security.pkcs11.SunPKCS11 \
    -providerArg yubikey.cfg \
    -signedjar signed.jar unsigned.jar "Private key for PIV Authentication"
```

--------------------------------

### Test Decryption with PIN Verification

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/test-decryption.adoc

Tests the decipher action by first verifying the PIN and then providing the certificate for decryption. Requires the certificate to be read beforehand.

```bash
$ yubico-piv-tool -a verify-pin -a test-decipher -s <slot> [ -P <PIN code> -i cert.pem ]
```

```bash
$ yubico-piv-tool -a verify-pin -a test-decipher -s 9a
Enter PIN: 
Successfully verified PIN.
Please paste the certificate to encrypt for...
-----BEGIN CERTIFICATE-----
MIIBuTCCAWCgAwIBAgIJAMOZXtijzEepMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
Fw0xOTA4MTMwODEwNDVaFw0yMDA4MTIwODEwNDVaMDgxETAPBgNVBAMMCHBpdl9h
dXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABKPfSKeNY204JiHsSUwDAV8GuYqZOHfJJxrT4E0q
VWsKdC5zwRc7xvb2YgbMonPW5BfIUi766/VwWN54UsqWVuWjUzBRMB0GA1UdDgQW
BBR/bpCmGr+ark0VbGX5UvYWy9dM9DAfBgNVHSMEGDAWgBR/bpCmGr+ark0VbGX5
UvYWy9dM9DAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIHZZe7Xm
s6y8LKEBqGnbr1cbniHgMrvM1ST6GpL27HuaAiB+UwjI21GxIsd5r2avmwvT5LeZ
gQBns9KNCIgkwx+/Iw==
-----END CERTIFICATE-----
Successfully performed ECDH exchange with card.
```

--------------------------------

### Display YubiKey Firmware Version

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/version.adoc

Use this command to display the firmware version of your YubiKey. No parameters are required.

```bash
$ yubico-piv-tool -a version
Firmware version 4.4.0 found.
```

--------------------------------

### Sign Data with Yubico PIV Tool

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/signing.adoc

Use this command to sign input data. It requires specifying the slot and can optionally take hash algorithm, key algorithm, PIN, input file, and output file. PIN verification is mandatory.

```bash
$ yubico-piv-tool -a verify-pin --sign -s 9c -H SHA512 -A RSA2048 -i data.txt -o data.sig
Enter PIN:
Successfully verified PIN.
Signature successful!
```

--------------------------------

### Import Large Certificate with GZIP Compression

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Imports a large certificate that has been compressed using GZIP. The certificate is placed into the specified slot, and the tool confirms successful import.

```bash
$ yubico-piv-tool -a import-certificate -s 9c -k -i cert_large.gz -K GZIP
Successfully imported a new certificate.
```

--------------------------------

### Import Certificate

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_generation.adoc

Imports a certificate into the specified slot. Requires authentication with the management key.

```bash
$ yubico-piv-tool -a import-certificate -s <slot> -k [ -o <cert file> ]
```

--------------------------------

### Display Device Info with pkcs11-tool

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/pkcs11tool.adoc

Use this command to display information about the connected YubiKey device when using the YKCS11 module.

```bash
$ pkcs11-tool --module /path/to/libykcs11.so --show-info
```

--------------------------------

### Use YubiKey with OpenSSL PKCS#11 Engine

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Commands for signing data and creating CSRs using the OpenSSL PKCS#11 engine.

```bash
# Install OpenSSL PKCS#11 engine
# (libp11 or pkcs11 engine depending on distribution)

# Sign with YubiKey via OpenSSL engine
$ openssl dgst -engine pkcs11 -keyform engine \
    -sign "pkcs11:object=Private%20key%20for%20Digital%20Signature;type=private" \
    -sha256 -out signature.bin document.txt

# Create CSR using YubiKey
$ openssl req -new -engine pkcs11 -keyform engine \
    -key "pkcs11:object=Private%20key%20for%20PIV%20Authentication;type=private" \
    -out request.csr -subj "/CN=user@example.com"
```

--------------------------------

### Download and Verify Certificate Chain

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Downloads the Yubico root CA and verifies an attestation or intermediate certificate chain using OpenSSL.

```bash
# Download Yubico root CA and verify chain
$ curl https://developers.yubico.com/PKI/yubico-piv-ca-1.pem -o root_ca.pem
$ openssl verify -CAfile root_ca.pem -untrusted intermediate.pem attestation_9a.pem
attestation_9a.pem: OK
```

--------------------------------

### Generate Attestation and Metadata in C

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Functions for generating attestation certificates and parsing key metadata using the ykpiv library.

```c
#include <ykpiv/ykpiv.h>

int generate_attestation(ykpiv_state *state, uint8_t slot) {
    ykpiv_rc rc;
    unsigned char attest_cert[4096];
    size_t attest_len = sizeof(attest_cert);

    // Generate attestation certificate for the key in slot
    rc = ykpiv_attest(state, slot, attest_cert, &attest_len);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Attestation failed: %s\n", ykpiv_strerror(rc));
        return -1;
    }

    printf("Attestation certificate: %zu bytes\n", attest_len);
    // attest_cert contains DER-encoded attestation certificate
    // Signed by the key in slot f9

    return 0;
}

int get_key_metadata(ykpiv_state *state, uint8_t slot) {
    ykpiv_rc rc;
    unsigned char metadata[1024];
    size_t meta_len = sizeof(metadata);

    rc = ykpiv_get_metadata(state, slot, metadata, &meta_len);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Failed to get metadata: %s\n", ykpiv_strerror(rc));
        return -1;
    }

    // Parse metadata
    ykpiv_metadata meta;
    rc = ykpiv_util_parse_metadata(metadata, meta_len, &meta);
    if (rc == YKPIV_OK) {
        printf("Algorithm: 0x%02x\n", meta.algorithm);
        printf("PIN Policy: 0x%02x\n", meta.pin_policy);
        printf("Touch Policy: 0x%02x\n", meta.touch_policy);
        printf("Origin: %s\n",
               meta.origin == YKPIV_METADATA_ORIGIN_GENERATED ? "Generated" : "Imported");
    }

    return 0;
}
```

--------------------------------

### Sign Data with RSA Key and Verify with openssl

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/pkcs11tool.adoc

Signs data using an RSA key in a specified slot and verifies the signature using openssl. Ensure the public key is exported first.

```bash
$ pkcs11-tool --module /path/to/libykcs11.so --sign --id 4 -i data.txt -o data.sig
$ openssl rsautl -verify -in data.sig -inkey 9e_pubkey.pem -pubin
```

--------------------------------

### Display Device Status and All Slot Contents

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/status.adoc

Use this command to view the YubiKey's metadata and the contents of slots 9a, 9c, 9d, and 9e. No specific slot is targeted, so all default slots are displayed.

```bash
$ yubico-piv-tool -a status
Version:	4.4.0
Serial Number:	12345678
CHUID:	No data available
CCC:	No data available
Slot 9a:
		Private Key Algorithm:	RSA2048
            Public Key Algorithm:	RSA2048
		Subject DN:	CN=piv_auth, C=SE
		Issuer DN:	CN=TestCA, O=Yubico, C=SE
		Fingerprint:	4a1416fce853b29eaf520174bf8639d72ff30bd84e4586f81ac2a19eda43fdf1
		Not Before:	Aug  8 14:29:23 2019 GMT
		Not After:	Aug  7 14:29:23 2021 GMT
Slot 9c:
		Private Key Algorithm:	ECCP384
		Public Key Algorithm:	RSA2048
		Subject DN:	CN=sign, C=SE
		Issuer DN:	CN=TestCA, O=Yubico, C=SE
		Fingerprint:	803a89d5e196835d4a7e5e600e413fec1d3014712fcfd9e31fe15010829226dd
		Not Before:	Aug  8 14:29:50 2019 GMT
		Not After:	Aug  7 14:29:50 2021 GMT
            WARNING: Slot private key and certificate do not match
Slot 9d:
		Private Key Algorithm:	RSA2048
            Public Key Algorithm:	RSA2048
		Subject DN:	CN=key_mgm, C=SE
		Issuer DN:	CN=TestCA, O=Yubico, C=SE
		Fingerprint:	4a1416fce853429eaf420074bf8d39d72ff30bd84e4586f81ac2a19eda43fdf1
		Not Before:	Aug  8 14:29:23 2019 GMT
		Not After:	Aug  7 14:29:23 2021 GMT
            WARNING: Slot private key and certificate do not match
Slot 9e:
		Private Key Algorithm:	RSA2048
            Public Key Algorithm:	RSA2048
		Subject DN:	CN=card_auth, C=SE
		Issuer DN:	CN=TestCA, O=Yubico, C=SE
		Fingerprint:	803a89d5e196845d4a7e5e6006413fec1d30157128cfd9e3afe15010829226dd
		Not Before:	Aug  8 14:29:50 2019 GMT
		Not After:	Aug  7 14:29:50 2021 GMT
    PIN tries left:	3
```

--------------------------------

### Create Self-Signed Certificate with yubico-piv-tool

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Generates a self-signed X.509 certificate using an existing key on the YubiKey. Requires PIN verification.

```bash
# Create self-signed certificate for slot 9a
$ yubico-piv-tool -a verify-pin -a selfsign -s 9a -S '/CN=piv_auth/OU=test/O=example.com/' -i public.pem -o cert.pem
Enter PIN:
Successfully verified PIN.
-----BEGIN CERTIFICATE-----
MIIBujCCAWCgAwIBAgIJAJKWdUFfuvqiMAoGCCqGSM49BAMCMDgxETAPBgNVBAMM
CHBpdl9hdXRoMQ0wCwYDVQQLDAR0ZXN0MRQwEgYDVQQKDAtleGFtcGxlLmNvbTAe
...
-----END CERTIFICATE-----
Successfully generated a new self signed certificate.

# Combined command: generate key, verify PIN, self-sign, and import certificate
$ 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/'
```

--------------------------------

### Sign data using OpenSSL and PKCS11 engine

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/openssl_engine.adoc

Uses the PKCS11 engine to sign data with a private key stored on a YubiKey. Ensure the PKCS11_MODULE_PATH environment variable points to the correct libykcs11.so library.

```bash
$ PKCS11_MODULE_PATH=/path/to/libykcs11.so openssl rsautl -engine pkcs11 -keyform engine -inkey "pkcs11:object=Private key for PIVAuthentication;type=private" -sign -in data.txt -out data.sig
```

--------------------------------

### CLI Import Operations

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_import.adoc

Commands for importing keys, certificates, or both into specific Yubikey PIV slots.

```APIDOC
## CLI Action: import-key / import-certificate

### Description
Imports a key, a certificate, or both into the Yubikey PIV interface. Requires management key authentication.

### Parameters
#### Options
- **-s, --slot** (string) - Required - The key slot to operate on (e.g., 9a, 9c, 9d, 9e, 82-95, f9).
- **-k, --key** (string) - Required - Management key to use.
- **-i, --input** (string) - Optional - Filename to use as input (defaults to Stdin).
- **-K, --key-format** (string) - Optional - Format of the key/certificate (PEM, PKCS12, GZIP, DER, SSH).
- **-p, --password** (string) - Optional - Password for decryption of private key file.
- **-P, --pin** (string) - Optional - Pin/puk code for verification.
- **--pin-policy** (string) - Optional - Set pin policy (never, once, always, matchonce, matchalways).
- **--touch-policy** (string) - Optional - Set touch policy (never, always, cached).

### Request Example
$ yubico-piv-tool -a import-key -a import-certificate -s 9c -k -i key.pfx -K PKCS12

### Response
- **Success** - Returns confirmation message upon successful import.
```

--------------------------------

### Test RSA Keys with pkcs11-tool

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/pkcs11tool.adoc

Tests RSA key functionality on the YubiKey. Requires at least one RSA key to be pre-existing.

```bash
$ pkcs11-tool --module /path/to/libykcs11.so --login  --test
```

--------------------------------

### Display Status for a Specific Slot (f9)

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/status.adoc

This command demonstrates retrieving status information for slot 'f9', which typically contains attestation certificates. The output includes detailed certificate information.

```bash
$ yubico-piv-tool -a status -s f9
Version:	4.4.0
Serial Number:	12345678
CHUID:	3019d4e739da739ced39ce739d836858210842108421c84210c3eb3410461c7c766122b38b2edf05183c3d041a350832303330303130313e00fe00
CCC:	f015a000000116ff02f9a5b5f5fc5cd67c63a147ddf405f10121f20121f300f40100f50110f600f700fa00fb00fc00fd00fe00
Slot f9:
		Private Key Algorithm:	RSA2048
            Public Key Algorithm:	RSA2048
            Subject DN:	CN=Test Attestation Certificate
            Issuer DN:	CN=Test Attestation Certificate
            Fingerprint:	8dbc03bea80282748f0403de0922c93751fe498d376b6ae1aa87d1b8af74c7a3
            Not Before:	Jan 22 09:47:58 2018 GMT
            Not After:	Jan 24 09:47:58 2018 GMT
    PIN tries left:	3
```

--------------------------------

### Add Basic Test

Source: https://github.com/yubico/yubico-piv-tool/blob/master/lib/tests/CMakeLists.txt

Adds a CMake test named 'basic' that executes the 'test_basic' executable. The working directory is set to the build directory.

```cmake
add_test(
    NAME basic
    COMMAND test_basic
    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/lib/tests/
)
```

--------------------------------

### Generate Attestation Certificate

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Generates an attestation certificate for a key in a specified PIV slot, proving on-device key generation.

```bash
# Generate attestation for slot 9a
$ yubico-piv-tool -a attest -s 9a -o attestation_9a.pem
Successfully generated attestation certificate.
```

--------------------------------

### Generate RSA Keypair with pkcs11-tool

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/Supported_applications/pkcs11tool.adoc

Generates an RSA key pair in a specified slot with a given key size. Requires login as the SO user.

```bash
$ pkcs11-tool --module /path/to/libykcs11.so --login --login-type so --keypairgen --id 2 --key-type rsa:2048
```

--------------------------------

### Download Intermediate Certificates

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Attestation.adoc

Retrieves intermediate certificates required for verification on newer firmware versions.

```bash
$ curl https://developers.yubico.com/PKI/yubico-intermediate.pem -o AllIntermediateCerts.pem
```

--------------------------------

### Authenticate with Management Key in libykpiv

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Authenticate to the PIV application using either 3DES or AES management keys.

```c
#include <ykpiv/ykpiv.h>

int authenticate_mgm(ykpiv_state *state) {
    ykpiv_rc rc;

    // Default management key (3DES)
    unsigned char default_key[24] = {
        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
    };

    // Authenticate with 3DES key (24 bytes)
    rc = ykpiv_authenticate(state, default_key);
    if (rc != YKPIV_OK) {
        fprintf(stderr, "Authentication failed: %s\n", ykpiv_strerror(rc));
        return -1;
    }

    printf("Successfully authenticated with management key\n");
    return 0;
}

// For AES management keys (YubiKey 5+)
int authenticate_aes256(ykpiv_state *state) {
    unsigned char aes_key[32] = { /* 32-byte AES-256 key */ };

    // Use authenticate2 for variable-length keys
    ykpiv_rc rc = ykpiv_authenticate2(state, aes_key, sizeof(aes_key));
    return (rc == YKPIV_OK) ? 0 : -1;
}
```

--------------------------------

### Verify PIN with libykpiv

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Verify the user PIN to enable private key operations and check remaining retry attempts.

```c
#include <ykpiv/ykpiv.h>

int verify_pin(ykpiv_state *state, const char *pin) {
    ykpiv_rc rc;
    int tries_remaining = 0;

    // Verify PIN
    rc = ykpiv_verify(state, pin, &tries_remaining);

    switch (rc) {
        case YKPIV_OK:
            printf("PIN verified successfully\n");
            return 0;

        case YKPIV_WRONG_PIN:
            printf("Wrong PIN. %d tries remaining\n", tries_remaining);
            return -1;

        case YKPIV_PIN_LOCKED:
            printf("PIN is locked. Use PUK to unblock.\n");
            return -2;

        default:
            fprintf(stderr, "PIN verification error: %s\n", ykpiv_strerror(rc));
            return -3;
    }
}

// Get PIN retries without unverifying current session
int get_pin_retries(ykpiv_state *state) {
    int tries = 0;
    ykpiv_rc rc = ykpiv_get_pin_retries(state, &tries);
    if (rc == YKPIV_OK) {
        printf("PIN tries remaining: %d\n", tries);
    }
    return tries;
}
```

--------------------------------

### Move Key Command Syntax

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/key_move.adoc

General command structure for moving a key between PIV slots.

```bash
$ yubico-piv-tool -a move-key -s <slot> --to-slot <slot> -k
```

--------------------------------

### Verify PIN (libykpiv C API)

Source: https://context7.com/yubico/yubico-piv-tool/llms.txt

Verify the user PIN to enable private key operations.

```APIDOC
### Verify PIN

Verify the user PIN to enable private key operations.

```c
#include <ykpiv/ykpiv.h>

int verify_pin(ykpiv_state *state, const char *pin) {
    ykpiv_rc rc;
    int tries_remaining = 0;

    // Verify PIN
    rc = ykpiv_verify(state, pin, &tries_remaining);

    switch (rc) {
        case YKPIV_OK:
            printf("PIN verified successfully\n");
            return 0;

        case YKPIV_WRONG_PIN:
            printf("Wrong PIN. %d tries remaining\n", tries_remaining);
            return -1;

        case YKPIV_PIN_LOCKED:
            printf("PIN is locked. Use PUK to unblock.\n");
            return -2;

        default:
            fprintf(stderr, "PIN verification error: %s\n", ykpiv_strerror(rc));
            return -3;
    }
}

// Get PIN retries without unverifying current session
int get_pin_retries(ykpiv_state *state) {
    int tries = 0;
    ykpiv_rc rc = ykpiv_get_pin_retries(state, &tries);
    if (rc == YKPIV_OK) {
        printf("PIN tries remaining: %d\n", tries);
    }
    return tries;
}
```
```

--------------------------------

### Import Key and Set Touch Policy

Source: https://github.com/yubico/yubico-piv-tool/blob/master/README.adoc

Imports a private key into slot 85 and sets the touch policy for operations. This functionality is available on YubiKey 4 and 5 models. The key file (e.g., 'ikey.pem') must be provided.

```bash
yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem
```

--------------------------------

### Enable YKCS11 Debugging via Build

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/YKCS11/index.adoc

Rebuild the project with the YKCS11_DBG flag set to a value between 1 and 9 to enable verbose logging.

```bash
$ mkdir build; cd build
$ cmake .. -DYKCS11_DBG=2
$ make
$ sudo make install
```

--------------------------------

### Read Certificate Command Syntax

Source: https://github.com/yubico/yubico-piv-tool/blob/master/doc/Actions/read_certificate.adoc

General command structure for reading a certificate from a specified slot.

```bash
$ yubico-piv-tool -a read-certificate -s <slot> [ -o <cert.pem> -K <cert file format> ]
```
Tokens:
Raw