Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PIV attestation updates based on Bens feedback #513

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

PIV attestation updates based on Bens feedback #513

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e3f5b64
PIV attestation updates based on Bens feedback
csalas-yubico Nov 4, 2022
b51d69f
Corrections to the formfactor values, removed duplicate of formfactor…
csalas-yubico Jan 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 32 additions & 9 deletions content/PIV/Introduction/PIV_attestation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
== 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 link:../../yubico-piv-tool/Attestation.adoc[documentation].
This document describes the attestation feature added to the PIV module in YubiKey 4.3 and above. For the process and commands used to acquire an attestation, please see the yubico-piv-tool link:../../yubico-piv-tool/Attestation.adoc[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.
Attestation is used to prove that a certain asymmetric key has been generated on device and not imported. With additional constraints, other characteristics of that asymmetric key can also be proven.


=== 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.
PIV attestation is implemented by returning a signed X.509 certificate for the key that is attested. The certificate is only returned if the key has been generated on-device.

Some features of the generated certificate:

=== Certificate features:
Some characteristics of the generated certificate are :

* Serial will be a random 16 byte integer
* Issuer will be the subject of the attesting certificate
Expand All @@ -18,7 +23,7 @@ Some features of the generated certificate:
* 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:
X.509 Extensions are used in the generated certificate to pass additional information about the key. Details on these extensions are below:

* +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.
Expand All @@ -34,14 +39,32 @@ Extensions in the generated certificate:
* +1.3.6.1.4.1.41482.3.10+: FIPS Certified YubiKey
* +1.3.6.1.4.1.41482.3.11+: CSPN Certified YubiKey

The YubiKey comes with a pre-loaded attestation certificate signed by a link:piv-attestation-ca.pem[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.
The YubiKey comes factory-loaded with an attestation key and certificate signed by the link:piv-attestation-ca.pem[Yubico root PIV CA].

NOTE: If you have a YubiKey Preview device, the attestation certificate will
instead be signed by our link:piv-attestation-preview-ca.pem[Yubico PIV Preview CA].
If desired, the signing key and certificate in slot f9 can be customized by overwriting the factory-issued key with a new key and certificate.

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


In addition to its base functionality, the attestation can also be used to verify the device was authentically produced by Yubico.

However, verification of device authenticity is contingent on all of the following:

. The attestation key and certificate in slot f9 must be unmodified.
. The slot under attestation must have a key present that was generated on-device.
. The attestation, including certificates chaining up to the link:piv-attestation-ca.pem[Yubico root PIV CA], must be properly verified.

[NOTE]
====
If you have a YubiKey Preview device, the attestation certificate will instead be signed by our link:piv-attestation-preview-ca.pem[Yubico PIV Preview CA].
====

[NOTE]
====
The root cert for the Yubico PIV CA was updated on September 24, 2018. The prior PEM can be found link:piv-attestation-ca-old.pem[here]. YubiKey 4 Series manufactured prior to mid-2017 and some manufactured in 2018 were signed with link:https://developers.yubico.com/u2f/yubico-u2f-ca-certs.txt[Yubico's U2F Attestation CA].

For more information on support added to the current root certificate, see link:https://support.yubico.com/support/solutions/articles/15000013406-piv-attestation-verification-fails-with-openssl-1-1-0[PIV Attestation Verification Fails with OpenSSL 1.1.0].
====
====