3.1 Authenticator Attestation GUID (AAGUID) typedef

typedef DOMString AAGUID;

3.2 CodeAccuracyDescriptor dictionary

The CodeAccuracyDescriptor describes the relevant accuracy/complexity aspects of passcode user verification methods.

dictionary CodeAccuracyDescriptor {
    required unsigned short base;
    required unsigned short minLength;
    unsigned short          maxRetries;
    unsigned short          blockSlowdown;
};

3.3 BiometricAccuracyDescriptor dictionary

The BiometricAccuracyDescriptor describes relevant accuracy/complexity aspects in the case of a biometric user verification method.

At least one of the values MUST be set. If the vendor doesn't want to specify such values, then VerificationMethodDescriptor.baDesc MUST be omitted.

dictionary BiometricAccuracyDescriptor {
    double         FAR;
    double         FRR;
    double         EER;
    double         FAAR;
    unsigned short maxReferenceDataSets;
    unsigned short maxRetries;
    unsigned short blockSlowdown;
};

3.4 PatternAccuracyDescriptor dictionary

The PatternAccuracyDescriptor describes relevant accuracy/complexity aspects in the case that a pattern is used as the user verification method.

dictionary PatternAccuracyDescriptor {
    required unsigned long minComplexity;
    unsigned short         maxRetries;
    unsigned short         blockSlowdown;
};

3.5 VerificationMethodDescriptor dictionary

A descriptor for a specific base user verification method as implemented by the authenticator.

A base user verification method must be chosen from the list of those described in [FIDORegistry]

The specification of the related AccuracyDescriptor is optional, but recommended.

dictionary VerificationMethodDescriptor {
    required unsigned long      userVerification;
    CodeAccuracyDescriptor      caDesc;
    BiometricAccuracyDescriptor baDesc;
    PatternAccuracyDescriptor   paDesc;
};

3.6 verificationMethodANDCombinations typedef

typedef VerificationMethodDescriptor[] VerificationMethodANDCombinations;

3.7 rgbPaletteEntry dictionary

The rgbPaletteEntry is an RGB three-sample tuple palette entry

dictionary rgbPaletteEntry {
    required unsigned short r;
    required unsigned short g;
    required unsigned short b;
};

3.8 DisplayPNGCharacteristicsDescriptor dictionary

The DisplayPNGCharacteristicsDescriptor describes a PNG image characteristics as defined in the PNG [PNG] spec for IHDR (image header) and PLTE (palette table)

dictionary DisplayPNGCharacteristicsDescriptor {
    required unsigned long width;
    required unsigned long height;
    required octet         bitDepth;
    required octet         colorType;
    required octet         compression;
    required octet         filter;
    required octet         interlace;
    rgbPaletteEntry[]      plte;
};

3.9 EcdaaTrustAnchor dictionary

In the case of ECDAA attestation, the ECDAA-Issuer's trust anchor MUST be specified in this field.

dictionary EcdaaTrustAnchor {
    required DOMString X;
    required DOMString Y;
    required DOMString c;
    required DOMString sx;
    required DOMString sy;
    required DOMString G1Curve;
};

3.10 ExtensionDescriptor dictionary

dictionary ExtensionDescriptor {
    required DOMString id;
    unsigned short     tag;
    DOMString          data;
    required boolean   fail_if_unknown;
};

3.11 AlternativeDescriptions dictionary

dictionary AlternativeDescriptions {
    DOMString *IETFLanguageCodes-members...;
};

4.1 Dictionary MetadataStatement Members

legalHeader of type DOMString

The legalHeader, if present, contains a legal guide for accessing and using metadata, which itself MAY contain URL(s) pointing to further information, such as a full Terms and Conditions statement.

aaid of type AAID

The Authenticator Attestation ID. See [UAFProtocol] for the definition of the AAID structure. This field MUST be set if the authenticator implements FIDO UAF.

Note

FIDO UAF Authenticators support AAID, but they don't support AAGUID.

aaguid of type AAGUID

The Authenticator Attestation GUID. See [FIDOKeyAttestation] for the definition of the AAGUID structure. This field MUST be set if the authenticator implements FIDO 2.

Note

FIDO 2 Authenticators support AAGUID, but they don't support AAID.

attestationCertificateKeyIdentifiers of type array of DOMString

A list of the attestation certificate public key identifiers encoded as hex string. This value MUST be calculated according to method 1 for computing the keyIdentifier as defined in [RFC5280] section 4.2.1.2. The hex string MUST NOT contain any non-hex characters (e.g. spaces). All hex letters MUST be lower case. This field MUST be set if neither aaid nor aaguid are set. Setting this field implies that the attestation certificate(s) are dedicated to a single authenticator model.

All attestationCertificateKeyIdentifier values should be unique within the scope of the Metadata Service.

Note

FIDO U2F Authenticators typically do not support AAID nor AAGUID, but they use attestation certificates dedicated to a single authenticator model.

description of type required DOMString

A human-readable, short description of the authenticator, in English.

Note

This description should help an administrator configuring authenticator policies. This description might deviate from the description returned by the ASM for that authenticator.

This description should contain the public authenticator trade name and the publicly known vendor name.

This description MUST be in English, and only contain ASCII [ECMA-262] characters.

This description SHALL NOT exceed a maximum length of 200 characters.

alternativeDescriptions of type AlternativeDescriptions

A list of human-readable short descriptions of the authenticator in different languages.

authenticatorVersion of type required unsigned short

Earliest (i.e. lowest) trustworthy authenticatorVersion meeting the requirements specified in this metadata statement.

Adding new StatusReport entries with status UPDATE_AVAILABLE to the metadata TOC object [FIDOMetadataService] MUST also change this authenticatorVersion if the update fixes severe security issues, e.g. the ones reported by preceding StatusReport entries with status code USER_VERIFICATION_BYPASS, ATTESTATION_KEY_COMPROMISE, USER_KEY_REMOTE_COMPROMISE, USER_KEY_PHYSICAL_COMPROMISE, REVOKED.

It is RECOMMENDED to assume increased risk if this version is higher (newer) than the firmware version present in an authenticator. For example, if a StatusReport entry with status USER_VERIFICATION_BYPASS or USER_KEY_REMOTE_COMPROMISE precedes the UPDATE_AVAILABLE entry, than any firmware version lower (older) than the one specified in the metadata statement is assumed to be vulnerable.

protocolFamily of type DOMString

The FIDO protocol family. The values "uaf", "u2f", and "fido2" are supported. If this field is missing, the assumed protocol family is "uaf". Metadata Statements for U2F authenticators MUST set the value of protocolFamily to "u2f" and FIDO 2.0/WebAuthentication Authenticator implementations MUST set the value of protocolFamily to "fido2".

upv of type array of required Version

The FIDO unified protocol version(s) (related to the specific protocol family) supported by this authenticator. See [UAFProtocol] for the definition of the Version structure.

assertionScheme of type required DOMString

The assertion scheme supported by the authenticator. Must be set to one of the enumerated strings defined in the FIDO UAF Registry of Predefined Values [UAFRegistry], or to "U2FV1BIN" in the case of the U2F raw message format, or to "FIDOV2" in the case of the FIDO 2/WebAuthentication assertion scheme.

authenticationAlgorithm of type required unsigned short

The preferred authentication algorithm supported by the authenticator. Must be set to one of the ALG_ constants defined in the FIDO Registry of Predefined Values [FIDORegistry]. This value MUST be non-zero.

authenticationAlgorithms of type array of unsigned short

The list of authentication algorithms supported by the authenticator. Must be set to the complete list of the supported ALG_ constants defined in the FIDO Registry of Predefined Values [FIDORegistry] if the authenticator supports multiple algorithms. Each value MUST be non-zero.

Note

FIDO UAF Authenticators

For verification purposes, the field SignatureAlgAndEncoding in the FIDO UAF authentication assertion [UAFAuthnrCommands] should be used to determine the actual signature algorithm and encoding.

FIDO U2F Authenticators

FIDO U2F only supports one signature algorithm and encoding: ALG_SIGN_SECP256R1_ECDSA_SHA256_RAW [FIDORegistry].

publicKeyAlgAndEncoding of type required unsigned short

The preferred public key format used by the authenticator during registration operations. Must be set to one of the ALG_KEY constants defined in the FIDO Registry of Predefined Values [FIDORegistry]. Because this information is not present in APIs related to authenticator discovery or policy, a FIDO server MUST be prepared to accept and process any and all key representations defined for any public key algorithm it supports. This value MUST be non-zero.

publicKeyAlgAndEncodings of type array of unsigned short

The list of public key formats supported by the authenticator during registration operations. Must be set to the complete list of the supported ALG_KEY constants defined in the FIDO Registry of Predefined Values [FIDORegistry] if the authenticator model supports multiple encodings. Because this information is not present in APIs related to authenticator discovery or policy, a FIDO server MUST be prepared to accept and process any and all key representations defined for any public key algorithm it supports. Each value MUST be non-zero.

Note

FIDO UAF Authenticators

For verification purposes, the field PublicKeyAlgAndEncoding in the FIDO UAF registration assertion [UAFAuthnrCommands] should be used to determine the actual encoding of the public key.

FIDO U2F Authenticators

FIDO U2F only supports one public key encoding: ALG_KEY_ECC_X962_RAW [FIDORegistry].

attestationTypes of type array of required unsigned short

The supported attestation type(s). (e.g. TAG_ATTESTATION_BASIC_FULL(0x3E07), TAG_ATTESTATION_BASIC_SURROGATE(0x3E08)).
See section 4.1 of FIDO UAF Registry [UAFRegistry], section 5.2.1 of FIDO UAF Authenticator Commands specification [UAFAuthnrCommands], and section 4.1.2 of FIDO UAF Protocol specification [UAFProtocol] for details.

Note

Even though these tags are defined in FIDO UAF protocol specifications, the attestation types apply to authenticators of all protocol families (e.g. UAF, U2F, ...).

userVerificationDetails of type array of required VerificationMethodANDCombinations

A list of alternative VerificationMethodANDCombinations. Each of these entries is one alternative user verification method. Each of these alternative user verification methods might itself be an "AND" combination of multiple modalities.

All effectively available alternative user verification methods MUST be properly specified here. A user verification method is considered effectively available if this method can be used to either:

• enroll new verification reference data to one of the user verification methods

or

• unlock the UAuth key directly after successful user verification

keyProtection of type required unsigned short

A 16-bit number representing the bit fields defined by the KEY_PROTECTION constants in the FIDO Registry of Predefined Values [FIDORegistry].

This value MUST be non-zero.

Note

The keyProtection specified here denotes the effective security of the attestation key and Uauth private key and the effective trustworthiness of the attested attributes in the “sign assertion”. Effective security means that key extraction or injecting malicious attested attributes is only possible if the specified protection method is compromised. For example, if keyProtection=TEE is stated, it shall be impossible to extract the attestation key or the Uauth private key or to inject any malicious attested attributes without breaking the TEE.

isKeyRestricted of type boolean

This entry is set to true, if the Uauth private key is restricted by the authenticator to only sign valid FIDO signature assertions.

This entry is set to false, if the authenticator doesn't restrict the Uauth key to only sign valid FIDO signature assertions. In this case, the calling application could potentially get any hash value signed by the authenticator.

If this field is missing, the assumed value is isKeyRestricted=true

.

Note

Note that only in the case of isKeyRestricted=true, the FIDO server can trust a signature counter or transaction text to have been correctly processed/controlled by the authenticator.

isFreshUserVerificationRequired of type boolean

This entry is set to true, if Uauth key usage always requires a fresh user verification.

If this field is missing, the assumed value is isFreshUserVerificationRequired=true.

This entry is set to false, if the Uauth key can be used without requiring a fresh user verification, e.g. without any additional user interaction, if the user was verified a (potentially configurable) caching time ago.

In the case of isFreshUserVerificationRequired=false, the FIDO server MUST verify the registration response and/or authentication response and verify that the (maximum) caching time (sometimes also called "authTimeout") is acceptable.

This entry solely refers to the user verification. In the case of transaction confirmation, the authenticator MUST always ask the user to authorize the specific transaction.

Note

Note that in the case of isFreshUserVerificationRequired=false, the calling App could trigger use of the key without user involvement. In this case it is the responsibility of the App to ask for user consent.

matcherProtection of type required unsigned short

A 16-bit number representing the bit fields defined by the MATCHER_PROTECTION constants in the FIDO Registry of Predefined Values [FIDORegistry].

This value MUST be non-zero.

Note

If multiple matchers are implemented, then this value must reflect the weakest implementation of all matchers.

The matcherProtection specified here denotes the effective security of the FIDO authenticator’s user verification. This means that a false positive user verification implies breach of the stated method. For example, if matcherProtection=TEE is stated, it shall be impossible to trigger use of the Uauth private key when bypassing the user verification without breaking the TEE.

cryptoStrength of type unsigned short

The authenticator's overall claimed cryptographic strength in bits (sometimes also called security strength or security level). This is the minimum of the cryptographic strength of all involved cryptographic methods (e.g. RNG, underlying hash, key wrapping algorithm, signing algorithm, attestation algorithm), e.g. see [FIPS180-4], [FIPS186-4], [FIPS198-1], [SP800-38B], [SP800-38C], [SP800-38D], [SP800-38F], [SP800-90C], [SP800-90ar1], [FIPS140-2] etc.

If this value is absent, the cryptographic strength is unknown. If the cryptographic strength of one of the involved cryptographic methods is unknown the overall claimed cryptographic strength is also unknown.

operatingEnv of type DOMString

Description of the particular operating environment that is used for the Authenticator. These are specified in [FIDORestrictedOperatingEnv].

attachmentHint of type required unsigned long

A 32-bit number representing the bit fields defined by the ATTACHMENT_HINT constants in the FIDO Registry of Predefined Values [FIDORegistry].

Note

The connection state and topology of an authenticator may be transient and cannot be relied on as authoritative by a relying party, but the metadata field should have all the bit flags set for the topologies possible for the authenticator. For example, an authenticator instantiated as a single-purpose hardware token that can communicate over bluetooth should set ATTACHMENT_HINT_EXTERNAL but not ATTACHMENT_HINT_INTERNAL.

isSecondFactorOnly of type required boolean

Indicates if the authenticator is designed to be used only as a second factor, i.e. requiring some other authentication method as a first factor (e.g. username+password).

tcDisplay of type required unsigned short

A 16-bit number representing a combination of the bit flags defined by the TRANSACTION_CONFIRMATION_DISPLAY constants in the FIDO Registry of Predefined Values [FIDORegistry].

This value MUST be 0, if transaction confirmation is not supported by the authenticator.

Note

The tcDisplay specified here denotes the effective security of the authenticator’s transaction confirmation display. This means that only a breach of the stated method allows an attacker to inject transaction text to be included in the signature assertion which hasn't been displayed and confirmed by the user.

tcDisplayContentType of type DOMString

Supported MIME content type [RFC2049] for the transaction confirmation display, such as text/plain or image/png.

This value MUST be present if transaction confirmation is supported, i.e. tcDisplay is non-zero.

tcDisplayPNGCharacteristics of type array of DisplayPNGCharacteristicsDescriptor

A list of alternative DisplayPNGCharacteristicsDescriptor. Each of these entries is one alternative of supported image characteristics for displaying a PNG image.

This list MUST be present if PNG-image based transaction confirmation is supported, i.e. tcDisplay is non-zero and tcDisplayContentType is image/png.

attestationRootCertificates of type array of required DOMString

Each element of this array represents a PKIX [RFC5280] X.509 certificate that is a valid trust anchor for this authenticator model. Multiple certificates might be used for different batches of the same model. The array does not represent a certificate chain, but only the trust anchor of that chain. A trust anchor can be a root certificate, an intermediate CA certificate or even the attestation certificate itself.

Each array element is a base64-encoded (section 4 of [RFC4648]), DER-encoded [ITU-X690-2008] PKIX certificate value. Each element MUST be dedicated for authenticator attestation.

Note

A certificate listed here is a trust anchor. It might be the actual certificate presented by the authenticator, or it might be an issuing authority certificate from the vendor that the actual certificate in the authenticator chains to.

In the case of "uaf" protocol family, the attestation certificate itself and the ordered certificate chain are included in the registration assertion (see [UAFAuthnrCommands]).

Either

1. the manufacturer attestation trust anchor

or

2. the trust anchor dedicated to a specific authenticator model

MUST be specified.

In the case (1), the trust anchor certificate might cover multiple authenticator models. In this case, it must be possible to uniquely derive the authenticator model from the Attestation Certificate. When using AAID or AAGUID, this can be achieved by either specifying the AAID or AAGUID in the attestation certificate using the extension id-fido-gen-ce-aaid { 1 3 6 1 4 1 45724 1 1 1 } or id-fido-gen-ce-aaguid { 1 3 6 1 4 1 45724 1 1 4 } or - when neither AAID nor AAGUID are defined - by using the attestationCertificateKeyIdentifier method.

In the case (2) this is not required as the trust anchor only covers a single authenticator model.

When supporting surrogate basic attestation only (see [UAFProtocol], section "Surrogate Basic Attestation"), no attestation trust anchor is required/used. So this array MUST be empty in that case.

ecdaaTrustAnchors of type array of EcdaaTrustAnchor

A list of trust anchors used for ECDAA attestation. This entry MUST be present if and only if attestationType includes TAG_ATTESTATION_ECDAA. The entries in attestationRootCertificates have no relevance for ECDAA attestation. Each ecdaaTrustAnchor MUST be dedicated to a single authenticator model (e.g as identified by its AAID/AAGUID).

icon of type DOMString

A data: url [RFC2397] encoded PNG [PNG] icon for the Authenticator.

supportedExtensions[] of type ExtensionDescriptor

List of extensions supported by the authenticator.