OpenPGP Attestation

Introduction

This document describes the attestation feature added to the OpenPGP module in YubiKey 5.2. For generating attestation certificates, you can use YubiKey Manager CLI (ykman) version 3.1.0 or higher.

Purpose

The concept of attestation is to cryptographically certify that a certain asymmetric key has been generated on device, and not imported. This can be used to prove that no other copies of the asymmetric key exist.

Terminology

Attestation Key

Private signature key to sign the generated Attestation Statement (also called Attesting Key)

Attestation Certificate

X.509 certificate for the Attestation Key, used as template for Attestation Statement

Attestated Key

OpenPGP signature, decryption, or authentication key to attest was generated on device

Attestation Statement

Generated X.509 certificate specifying the Attested Key details, signed by the Attestation Key

Implementation

Attestation generates a new X.509 certificate (the Attestation Statement) for the key that is to be attested (Attested Key). The certificate is based on a template X.509 certificate issued by a CA (Attestation Certificate), and signed by the matching Attestation Key. An attestation certificate can only be generated if the attested key has been generated on device. This certificate should only be used for the purpose of verifying that the key was generated in device, not for any other purposes.

Attestation is based on chain of trust:

Attestation__1.png

When an attestation statement is generated, it is placed in the OpenPGP cardholder certificate slot for the attested key. For example, if the signature key is attested, the attestation statement is placed in the SIG cardholder certificate slot (index 2 of DO 0x7F21). Any data currently stored in the cardholder certificate slot is overwritten.

The YubiKey is pre-loaded with an attestation certificate and matching attestation key issued by the Yubico CA. The template and key are replaceable, which permits an individual or organization to issue attestations verifiable with their own CA if they prefer. If replaced, the Yubico template can never be restored. The attestation key and certificate will not be cleared out by a reset of the device.

The attestation key can use any supported algorithm except curve25519. All keys, including curve25519, can be attested.

Attestation Statements are verified by validating the certificate chain in reverse:

Attestation__2.png

Some features of the generated Attestation Statement:

  • Serial will be a random 16 byte integer

  • Issuer will be the subject of the template Attestation Certificate

  • Dates will be copied from the template Attestation Certificate

  • Subject will be the string "YubiKey OPGP Attestation " with the attested slot appended ("SIG", "DEC", or "AUT")

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

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

Extensions in the generated certificate:

OID Type Description

1.3.6.1.4.1.41482.5.1

UTF-8 String

Cardholder name

1.3.6.1.4.1.41482.5.2

Integer

Attested key’s source
- 0x00: imported (not permitted)
- 0x01: generated on device

1.3.6.1.4.1.41482.5.3

Octet String (3)

YubiKey version number
ex: 050303 = 5.3.3

1.3.6.1.4.1.41482.5.4

Octet String (20)

Attested key’s fingerprint

1.3.6.1.4.1.41482.5.5

Octet String (4)

Attested key’s generation date

1.3.6.1.4.1.41482.5.6

Integer

Attested key’s signature counter (if applicable)

1.3.6.1.4.1.41482.5.7

Integer

YubiKey’s serial number

1.3.6.1.4.1.41482.5.8

Octet String (1)

User Interaction Flag (UIF)
- 0x00: touch disabled
- 0x01: touch enabled
- 0x02: touch permanent
- 0x03: touch cached
- 0x04: touch permanent, cached




1.3.6.1.4.1.41482.5.9

Octet String (1)

Form Factor
- 0x00: Unspecified
- 0x01: USB-A Keychain
- 0x02: USB-A Nano
- 0x03: USB-C Keychain
- 0x04: USB-C Nano
- 0x05: USB-C/Lightning Keychain





Note
Cardholder name, fingerprint, and generation date can be overwritten with the admin PIN (PW3). When verifying attestation statements, these fields should not be trusted. Always verify the public key, and regenerate the PGP fingerprint if needed.

Yubico CA

The pre-loaded attestation certificate is signed by a Yubico OPGP CA.

Protocol Specification

OpenPGP Attestation is an extension to the OpenPGP application on ISO Smart Card Operating Systems specification. The new tags and instructions are reserved from version 3.4 of the spec. Their usage is defined here.

Attestation Key (Data Objects)

The Attestation Key (ATT key), an asymmetric keypair of any supported algorithm except curve25519, is added as a fourth key (in addition to the existing SIG, DEC, and AUT). Importing or generating an ATT key uses the same underlying commands as the other keys.

Import and generation commands specify which key to load via a Control Reference Template (CRT). Since the ATT key is a second signature key, it must be addressed by using the complex CRT format, which allows specifying a Key ID.

Attestation Key identifiers:

Identifier Value (hex)

Key ID

81

CRT

B6 03 84 01 81

New Data Objects tags for Attestation Key metadata:

Data Object Description

0xDA

Algorithm Attributes

0xDB

Key Fingerprint

0xDC

CA Fingerprint

0xDD

Key Generation Date

0xD9

User Interaction Flag (UIF)

Setting the attestation key requires the administration PIN (PW3).

Attestation Certificate (Data Object)

The Attestation Certificate is stored in a dedicated DO with tag 0xFC, accessible via standard PUT DATA and GET DATA instructions.

The maximum size of the certificate is 2048 bytes.

Generate Attestation (Instruction)

A new instruction is added to generate the Attestation Statement. Note that the class is 0x80, indicating that it is not an ISO interindustry standard instruction.

APDU Field Value(s)

CLA

0x80

INS

0xFB

P1

0x01 (SIG), 0x02 (DEC), 0x03 (AUT)

P2

0x00

Lc

0x00

Data

None

Le

0x00

There is no response data.

Upon successful completion (SW 0x9000), the Attestation Statement is written to the corresponding Cardholder Certificate slot. The Attestation Statement can be retrieved via the normal GET DATA instruction to DO tag 0x7F21.

Note that the order is non-standard in the cardholder certificate DO, so the mapping is as follows:

P1 Value DO 7F21 Index Key

1

2

SIG

2

1

DEC

3

0

AUT

Protocol Diagram

The diagram below illustrates a rough overview of what happens when the YubiKey Manager creates and fetches an Attestation Statement:

Attestation__3.png