1. Home
  2. PIV
  3. Introduction
  4. PIV attestation

    PIV Attestation

    Introduction

    This document describes the attestation feature added to the PIV module in YubiKey 4.3 and 5. For actual commands to work with the attestation feature, please see the yubico-piv-tool documentation.

    Purpose

    The concept of attestation is used to show that a certain asymmetric key has been generated on device and not imported. Typically this would be used before creating a certificate.

    Implementation

    Attestation is implemented by creating a X.509 certificate for the key that is to be attested, this is only done if the key has been generated on device. This certificate should be used for the purpose of verifying that the key was generated in device. Additional information included in the Attestation Certificate can be used to provide information about the device the attested key was generated on.

    Some features of the generated certificate:

    • Serial will be a random 16 byte integer

    • Issuer will be the subject of the attesting certificate

    • Dates will be copied from the attesting certificate

    • Subject will be the string "YubiKey PIV Attestation " with the attested slot appended

    • If the attesting key is RSA the signature will be SHA256-PKCS#1v1.5

    • If the attesting key is EC the signature will be ECDSA-SHA256

    Extensions in the generated certificate:

    • 1.3.6.1.4.1.41482.3.3: Firmware version, encoded as 3 bytes, like: 040300 for 4.3.0

    • 1.3.6.1.4.1.41482.3.7: Serial number of the YubiKey, encoded as an integer.

    • 1.3.6.1.4.1.41482.3.8: Two bytes, the first encoding pin policy and the second touch policy

      • Pin policy: 01 - never, 02 - once per session, 03 - always

      • Touch policy: 01 - never, 02 - always, 03 - cached for 15s

    • 1.3.6.1.4.1.41482.3.9: Formfactor, encoded as one byte

      • USB-A Keychain: 01 (81 for FIPS Devices)

      • USB-A Nano: 02 (82 for FIPS Devices)

      • USB-C Keychain: 03 (83 for FIPS Devices)

      • USB-C Nano: 04 (84 for FIPS Devices)

      • Lightning and USB-C: 05 (85 for FIPS Devices)

    • 1.3.6.1.4.1.41482.3.10: FIPS Certified YubiKey (Only present on the factory-loaded Attestation certificate in slot f9. This certificate will be included as part of the attestation certificate chain)

    • 1.3.6.1.4.1.41482.3.11: CSPN Certified YubiKey (Only present on the factory-loaded Attestation certificate in slot f9. This certificate will be included as part of the attestation certificate chain)

    The YubiKey comes with a pre-loaded attestation certificate signed by a Yubico PIV CA. This can be overwritten by loading a new key and certificate to slot f9. After the Yubico key is overwritten it can not be brought back. The attestation key and certificate will not be cleared out by a reset of the device.

    Note
    		 If you have a YubiKey Preview device, the attestation certificate will instead be signed by our 2023 Yubico PIV Preview CA or Yubico PIV Preview CA (prior to 2023).
    Note

    The root cert for the Yubico PIV CA was updated on September 24, 2018. The prior PEM can be found here. YubiKey 4 Series manufactured prior to mid-2017 and some manufactured in 2018 were signed with Yubico’s U2F Attestation CA.

    For more information on support added to the current root certificate, see PIV Attestation Verification Fails with OpenSSL 1.1.0.