Skip to main content

Overview

Attestation refers to the ability of a security device to prove its own identity and for a relying party to attain details about the security device it was created on, and which manufacturer actually created said device.

How attestation works​

The attestation of a security device is facilitated by its digital attestation certificate, which exposes details such as its make and model; but more importantly the public key component of a key pair imported by the manufacturer during production. An attestation certificate is always specific to a company or model, for example, all YubiKey 5 series devices created within the same production batch possess the same attestation certificate, and similarly, an attestation certificate is shared amongst all iPhone 12 Pro devices produced in a batch. Ultimately, an attestation can always be used to cryptographically assert that a specific security device is being used when it is registered.

It is important to note that WebAuthn strives for an equal balance of security and privacy, and disincentivizes any mechanism that makes security keys uniquely identifiable. As such, in order to preserve user privacy and limit the ability of an RP to identify a user based solely on the attestation certificate presented during registration, FIDO guidance recommends to all manufacturers that each attestation certificate span at least 100,000 distributed devices within any given batch.

Before you start​

It is important to be aware that requiring attestation is an invasive policy, especially when used to restrict users' choice of authenticator. For some applications this is necessary; for most it is not. Similarly, attestation does not automatically make your users more secure. Attestation gives you information, but you have to know what to do with that information in order to get a security benefit from it; it is a powerful tool but does very little on its own. Attestation can help retrieve and verify additional information about an authenticator, and enforce some very basic policy based on it, but it is your responsibility to further leverage that information into improved security.

When in doubt, err towards being more permissive, because using a passkey is more secure than not using a passkey. It may still be useful to request and store attestation information for future reference - for example, to warn users if security issues are discovered in their authenticators - but we recommend that you do not require a trusted attestation unless you have specific reason to do so.

Example​

Below is a demonstration of how attestation can be used to enhance the user experience. Notice how without any additional input, the application is able to populate the credential list with information about the credential that the user used to register their initial passkey.

Also note the second passkey added to the user's account; some authenticators, especially copyable passkeys, are unable to send attestation. Because of this, there is no attestation to evaluate, so no information can be inferred about the make/model of the key. In this instance we are using TouchID on a Mac, that is leveraging a copyable passkey that can be synched to an iCloud Keychain.

Types of attestation​

The WebAuthn specification notes a few different options that a relying party can use to convey the type of attestation it wishes to receive, if allowed. This option is set by the attestation property in the PublicKeyCredentialCreationOptions that is sent during registration.

None​

The option none indicates to the client that the relying party has no interest in receiving an attestation statement. The client will still generate and send a passkey, but it will not include any of the information that will indicate the make/model.

Direct​

The option direct indicates to the client that the relying party will accept an attestation statement directly from the authenticator. The client should make no attempt to alter this data, and should directly pass whatever was generated by the authenticator.

This is the default option used in our project.

Indirect​

The option indirect indicates to the client that the relying party will accept an attestation statement, but the client can make its own determination on how to obtain the attestation data. In other words, the client may replace the attestation statement provided by the authenticator with its preferred data.

Enterprise​

The option enterprise indicates to the client that the relying party needs an attestation statement from the authenticator that may include authenticator specific information, such as serial number. The previous examples attempt to leverage privacy preserving principles that prevent a relying party from tracking specific authenticators across different service. While attestation should be privacy preserving, there are enterprise use cases where an authenticator needs to present specific information about itself. Note that enterprise attestation can only be used if the authenticator itself has the feature enabled, and the user has consented to allowing the origin to request the information. More information on enterprise attestation can be found here.

Attestation metadata​

Developers should be aware that the attestation statement included with a passkey only sends the minimum amount of information needed to validate the root of trust present on the authenticator. This data includes:

  • The AAGUID, which is the unique identifier given to every FIDO2 authenticator
  • Attestation signature, which can be verified using a manufacturer’s public key.

If this is the only data that is provided, then how does the relying party identify other device characteristics like model name, interfaces, manufacturer name, and other signals? Also, how is a developer supposed to manage all of this information, are they meant to maintain their own repository of device metadata?

The FIDO Alliance provides, and stewards the FIDO Metadata Service (MDS), which is a collection of metadata for authenticators. The MDS can be used to evaluate the root of trust sent with a credential during registration in order to identify the device, and correlate it to a metadata entry containing a variety of different data on the authenticator.

The repository is offered in the form of a BLOB hosted on a FIDO Alliance resource. If your application is connected to an external network, then you can download the BLOB using a cURL request, or you can download and self-host it for non-public facing resources hosted in your environment.

Yubico's java-webauthn-server library includes support for the MDS, where you are able to download the BLOB, and validate attestation statements.