Using Attestation

Introduction

This feature is only available in YubiKey 4.3 and above.

A description of how PIV attestation can be used is found at https://developers.yubico.com/PIV/Introduction/PIV_attestation.html

Usage

PIV attestation provides information on a key in a given PIV slot, information that is signed using the key stored in slot f9 of the YubiKey.

PIV slot f9 comes pre-loaded from the factory with a key and certificate signed by Yubico’s root PIV Certificate Authority (CA). This key and certificate can be customized.

Note

Once the Yubico factory-issued key or certificate is overwritten, they cannot be restored. The attestation key and certificate in slot f9 are not modified by a reset of the device.

After a key is generated in a given PIV slot, an attestation can be generated for that PIV slot.

The output of the attest command is a PEM encoded certificate, signed by the key in slot f9.

Verification

Important

While OpenSSL, as demonstrated below, can be used as a method to test the concept of attestation verification, verification should be properly evaluated for production purposes.

Note

These commands only apply when the signing key and certificate in PIV slot f9 have not been customized or overwritten.

Note

The yubico-piv-tool attest action will fail if there is no key in the slot under attestation, or if the key in the slot under attestation was imported.

To verify an attestation statement perform the following steps:

  1. Retrieve the root Yubico PIV CA certificate and place it in a file. This can be performed at the command line:

    curl https://developers.yubico.com/PIV/Introduction/piv-attestation-ca.pem -o TrustedCAcerts.pem
    
  2. Extract the intermediate signing certificate from slot f9 on the YubiKey:

    yubico-piv-tool --action=read-certificate --slot=f9 > SlotF9Intermediate.pem
    
  3. Generate an attestation for the key in the PIV slot. The following command generates an attestation for slot 9a:

    yubico-piv-tool --action=attest --slot=9a > Slot9Aattestation.pem
    
  4. Verify the attestation cryptographically. A demonstration of this capability using OpenSSL is below:

Note

The OpenSSL command below does not work with OpenSSL 1.1.0 when used with YubiKey 4 series products. To verify certificate chains for such devices, see PIV Attestation Verification Fails with OpenSSL 1.1.0.

openssl verify -CAfile TrustedCAcerts.pem -untrusted SlotF9Intermediate.pem Slot9Aattestation.pem
 attestation.pem: OK