Yubico PIV Tool

Attestation certificates are accessible via the YKCS11 module. They are regular X.509 certificates that share the same CKA_ID and public key as the key they are attesting.

Key characteristics:

• They are not stored in the YubiKey (CKA_TOKEN is FALSE).
• They are generated dynamically when accessed.

For YubiKey 4 or newer, you can set security policies for the slot containing the imported key using --pin-policy and --touch-policy.

PIN Policies:

• never: No PIN required.
• once: PIN required once.
• always: PIN required every time.
• matchonce: Applicable with biometric verification.
• matchalways: Applicable with biometric verification.

Note: Default policies are always on slot 9c and once on slots 9a, 9d, and 9e.

Touch Policies:

• never: No touch required.
• always: Touch required every time.
• cached: Touch required periodically (cached).

The PIV interface requires a specific sequence of actions to populate a slot with a private key and a certificate.

Standard Sequence:

1. Generate: Create the key pair (-a generate).
2. Verify: Authenticate the session (-a verify-pin).
3. Sign/Request: Create a self-signed cert (-a selfsign) or a CSR (-a request-certificate).
4. Import: Load the resulting certificate into the slot (-a import-certificate).

You can chain these actions into a single command to simplify the process.

# Combined command for generating a key, self-signing it, and importing it in one go
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/'

YKCS11 defines two user types mapped to specific operations:

• Regular User: Performs PIN-associated operations (using private key material).
• Security Officer (SO): Performs device management (using the management key).

Default Credentials

• Default User PIN: 123456
• Default Management Key: 010203040506070801020304050607080102030405060708

Authentication Methods

• PIN: Required for regular user operations. Subsequent operations might require a new login depending on the key's PIN policy. The module supports the CONTEXT_SPECIFIC user for this.
• PIN Policy "never": You can skip PIN verification for these keys by using VERIFY_NONE as the PIN.
• Fingerprint (YubiKey Bio): To trigger bio verification, attempt to login with an empty PIN or use VERIFY_BIO as the PIN. The YubiKey will blink while waiting for a scan.

YubiKeys with firmware version 5.7.0 or higher support encrypted communication via the SCP11b protocol. This protects sensitive communication (e.g., over NFC) from eavesdropping.

• CLI usage: Add the --enc flag to your command.
• Library usage (libykpiv): Open a connection with the encryption boolean set to true.

Note: In the current SCP11b implementation, the On-Card certificate (CERT.SD.ECKA) used to establish the session is not validated.

Code coverage is supported via lcov and CMake-codecov. This functionality currently requires using make rather than cmake --build.

1. Enable coverage during the configuration step with -DENABLE_COVERAGE=1.
2. Build the project using make.
3. Run tests using make test.
4. Generate the HTML report using make lcov.

$ cmake -DENABLE_COVERAGE=1 ..
$ make
$ make test
$ make lcov

The YKCS11 module is compatible with pkcs11-tool. Note that older versions of OpenSC (common on some Linux distributions) may cause errors; it is recommended to use a newer version of OpenSC.

To use the module, you must provide the path to libykcs11.so using the --module flag in your commands.

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

Use the delete-certificate action to remove a certificate from a specific PIV slot.

Important Notes:

• Private Keys: Deleting a certificate does not delete the corresponding private key unless that key is subsequently overwritten.
• Authentication: This action requires authentication using a management key. If you do not provide a key via the --key flag, the tool will prompt you to enter it manually. If no key is provided and no prompt occurs, it defaults to 010203040506070801020304050607080102030405060708.
• Security Warning: It is strongly recommended to change the YubiKey's PIN, PUK, and management key before use.

yubico-piv-tool -a delete-certificate -s <slot> -k

Use the import-key and import-certificate actions to import private keys, certificates, or both into a specific YubiKey PIV slot.

Key Constraints:

• The largest accepted keys are 2025 bytes for YubiKey NEO and 3049 bytes for YubiKey 5.
• Larger certificates may require compression (e.g., using GZIP format) to fit.
• This action can also be used to import decryption keys (typically found in slot 9d) into retired slots (82-95).

Authentication: Importing requires authentication via a management key. If the -k flag is provided without a value, the tool will prompt for it. If omitted, the tool attempts to use the default management key: 010203040506070801020304050607080102030405060708.

# Import both a key and a certificate from a PKCS12 file into slot 9c
$ yubico-piv-tool -a import-key -a import-certificate -s 9c -k -i key.pfx -K PKCS12