1. Notation
Type names, attribute names and element names are written as code
String literals are enclosed in “”, e.g. “iconLight”.
In formulas we use “|” to denote byte wise concatenation operations.
The notation base64url(byte[8..64])
reads as 8-64 bytes of data encoded in base64url, "Base 64 Encoding with URL and Filename Safe Alphabet" [RFC4648] without padding.
Following [WebIDL-ED], dictionary members are optional unless they are explicitly marked as required
.
WebIDL dictionary members MUST NOT have a value of null.
Unless otherwise specified, if a WebIDL dictionary member is DOMString, it MUST NOT be empty.
Unless otherwise specified, if a WebIDL dictionary member is a List, it MUST NOT be an empty list.
For definitions of terms, please refer to the FIDO Glossary [FIDOGlossary].
All diagrams, examples, notes in this specification are non-normative.
Note: Certain dictionary members need to be present in order to comply with FIDO requirements. Such members are marked in the WebIDL definitions found in this document, as required
. The keyword required
has been introduced by [WebIDL-ED], which is a work-in-progress. If you are using a WebIDL parser which implements [WebIDL], then you may remove the keyword required
from your WebIDL and use other means to ensure those fields are present.
1.1. Key Words
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
2. Overview
This section is not normative.This document specifies how convenience related details about authenticators can be retrieved.
These details can be used when showing existing credentials to the user.
For security related information about authenticators, look at the FIDO Metadata Service [FIDOMetadataService].
All details provided by the Convenience Metadata Service are also included in the FIDO Metadata Service [FIDOMetadataService].
3. Convenience Metadata Service Details
This section is normative.The details about authenticators as provided by this service originates from the authenticator vendors and hence provides a good way to consistently describe those authenticators across relying parties.
3.1. Convenience Metadata Format
3.1.1. FriendlyNames dictionary
This descriptor contains friendly names (e.g., public trade name) of the authenticator in multiple languages.
dictionary FriendlyNames { DOMString *IETFLanguageCodes-members...; };
- *IETFLanguageCodes-members...
-
IETF language codes ([RFC5646]), defined by a primary language subtag, followed by a region subtag based on a two-letter country code from [ISO3166] alpha-2 (usually written in upper case), e.g: Austrian-German - "de-AT". In case of absence of the specific territorial language definition, vendor should fallback to the more general language option, e.g: If "de" is given, but "de-AT" is missing, the use "de" entry instead. Description values can contain any UTF-8 characters.
For example:
{ "en-US": "FIDO Sample Security Key" }
Each entry SHOULD NOT exceed a maximum length of 63 characters to ensure proper display.
3.1.2. ConvenienceDetails dictionary
dictionary {
ConvenienceDetails FriendlyNames friendlyNames ;DOMString icon ;DOMString iconDark ;DOMString providerLogoLight ;DOMString providerLogoDark ; };
friendlyNames
, of type FriendlyNames-
A human-readable friendly name of the authenticator / passkey provider in multiple languages. The name is intended to be shown to end users. A name in English language ("en-US") is mandatory, localized names for other languages are optional.
icon
, of type DOMString-
A
data:
url [RFC2397] encoded [PNG] or [SVG11] (light mode) icon for the Authenticator (e.g., depicting the security key). This icon is intended to be shown to users by RPs. Use of [SVG11] format is mandatory if any of theiconDark
,providerLogoLight
and/orproviderLogoDark
is used in addition toicon
. Use of [SVG11] is recommended if onlyicon
is used. The icon is more specific than the provider logo and should be shown if present. iconDark
, of type DOMString-
A
data:
url [RFC2397] encoded [SVG11] dark mode icon for the Authenticator (e.g., depicting the security key). This icon is intended to be shown to users by RPs. The icon is more specific than the provider logo and should be shown if present. providerLogoLight
, of type DOMString-
A
data:
url [RFC2397] encoded [SVG11] light mode icon for the provider (e.g., logomark of the passkey provider). The SVG MUST meet all of the requirements defined in § 4 SVG requirements. This icon is intended to be shown to users by RPs. providerLogoDark
, of type DOMString-
A
data:
url [RFC2397] encoded [SVG11] dark mode icon for the provider (e.g., logomark of the passkey provider). The SVG MUST meet all of the requirements defined in § 4 SVG requirements. This icon is intended to be shown to users by RPs.
3.1.3. Convenience Metadata Payload Entry dictionary
Represents the ConvenienceMetadataPayload
dictionary ConvenienceMetadataPayload { required Number no; DOMString *AAGUIDandConvenienceDetails...; };
- no
-
The serial number of this Metadata BLOB Payload. This serial number MUST be incremented whenever the contents of the Convenience Metadata Payload BLOB or the full Metadata Payload BLOB [FIDOMetadataService] changes. Serial numbers MUST be consecutive and strictly monotonic, i.e. the successor BLOB will have a
no
value exactly incremented by one. - *AAGUIDandConvenienceDetails...
-
Authenticator AAGUID followed by the ConvenienceDetails.
{ "no": 85, "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4": { "friendlyNames": {"en-US": "Google Password Manager"}, "providerLogoDark": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgaGVpZ2h0PSIyNHB4IiB2aWV3Qm94PSIwIDAgMTkyIDE5MiIgd2lkdGg9IjI0cHgiIHZlcnNpb249IjEuMiIgYmFzZVByb2ZpbGU9InRpbnktcHMiPjx0aXRsZT5Hb29nbGUgUGFzc3dvcmQgTWFuYWdlcjwvdGl0bGU+PHJlY3QgZmlsbD0ibm9uZSIgaGVpZ2h0PSIxOTIiIHdpZHRoPSIxOTIiIHk9IjAiPjwvcmVjdD48Zz48cGF0aCBkPSJNNjkuMjksMTA2Yy0zLjQ2LDUuOTctOS45MSwxMC0xNy4yOSwxMGMtMTEuMDMsMC0yMC04Ljk3LTIwLTIwczguOTctMjAsMjAtMjAgYzcuMzgsMCwxMy44Myw0LjAzLDE3LjI5LDEwaDI1LjU1QzkwLjMsNjYuNTQsNzIuODIsNTIsNTIsNTJDMjcuNzQsNTIsOCw3MS43NCw4LDk2czE5Ljc0LDQ0LDQ0LDQ0YzIwLjgyLDAsMzguMy0xNC41NCw0Mi44NC0zNCBINjkuMjl6IiBmaWxsPSIjNDI4NUY0Ij48L3BhdGg+PHJlY3QgZmlsbD0iI0ZCQkMwNCIgaGVpZ2h0PSIyNCIgd2lkdGg9IjQ0IiB4PSI5NCIgeT0iODQiPjwvcmVjdD48cGF0aCBkPSJNOTQuMzIsODRINjh2MC4wNWMyLjUsMy4zNCw0LDcuNDcsNCwxMS45NXMtMS41LDguNjEtNCwxMS45NVYxMDhoMjYuMzIgYzEuMDgtMy44MiwxLjY4LTcuODQsMS42OC0xMlM5NS40MSw4Ny44Miw5NC4zMiw4NHoiIGZpbGw9IiNFQTQzMzUiPjwvcGF0aD48cGF0aCBkPSJNMTg0LDEwNnYyNmgtMTZ2LThjMC00LjQyLTMuNTgtOC04LThzLTgsMy41OC04LDh2OGgtMTZ2LTI2SDE4NHoiIGZpbGw9IiMzNEE4NTMiPjwvcGF0aD48cmVjdCBmaWxsPSIjMTg4MDM4IiBoZWlnaHQ9IjI0IiB3aWR0aD0iNDgiIHg9IjEzNiIgeT0iODQiPjwvcmVjdD48L2c+PC9zdmc+", "providerLogoLight": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgaGVpZ2h0PSIyNHB4IiB2aWV3Qm94PSIwIDAgMTkyIDE5MiIgd2lkdGg9IjI0cHgiIHZlcnNpb249IjEuMiIgYmFzZVByb2ZpbGU9InRpbnktcHMiPjx0aXRsZT5Hb29nbGUgUGFzc3dvcmQgTWFuYWdlcjwvdGl0bGU+PHJlY3QgZmlsbD0ibm9uZSIgaGVpZ2h0PSIxOTIiIHdpZHRoPSIxOTIiIHk9IjAiPjwvcmVjdD48Zz48cGF0aCBkPSJNNjkuMjksMTA2Yy0zLjQ2LDUuOTctOS45MSwxMC0xNy4yOSwxMGMtMTEuMDMsMC0yMC04Ljk3LTIwLTIwczguOTctMjAsMjAtMjAgYzcuMzgsMCwxMy44Myw0LjAzLDE3LjI5LDEwaDI1LjU1QzkwLjMsNjYuNTQsNzIuODIsNTIsNTIsNTJDMjcuNzQsNTIsOCw3MS43NCw4LDk2czE5Ljc0LDQ0LDQ0LDQ0YzIwLjgyLDAsMzguMy0xNC41NCw0Mi44NC0zNCBINjkuMjl6IiBmaWxsPSIjNDI4NUY0Ij48L3BhdGg+PHJlY3QgZmlsbD0iI0ZCQkMwNCIgaGVpZ2h0PSIyNCIgd2lkdGg9IjQ0IiB4PSI5NCIgeT0iODQiPjwvcmVjdD48cGF0aCBkPSJNOTQuMzIsODRINjh2MC4wNWMyLjUsMy4zNCw0LDcuNDcsNCwxMS45NXMtMS41LDguNjEtNCwxMS45NVYxMDhoMjYuMzIgYzEuMDgtMy44MiwxLjY4LTcuODQsMS42OC0xMlM5NS40MSw4Ny44Miw5NC4zMiw4NHoiIGZpbGw9IiNFQTQzMzUiPjwvcGF0aD48cGF0aCBkPSJNMTg0LDEwNnYyNmgtMTZ2LThjMC00LjQyLTMuNTgtOC04LThzLTgsMy41OC04LDh2OGgtMTZ2LTI2SDE4NHoiIGZpbGw9IiMzNEE4NTMiPjwvcGF0aD48cmVjdCBmaWxsPSIjMTg4MDM4IiBoZWlnaHQ9IjI0IiB3aWR0aD0iNDgiIHg9IjEzNiIgeT0iODQiPjwvcmVjdD48L2c+PC9zdmc+" }, "08987058-cadc-4b81-b6e1-30de50dcbe96": { "friendlyNames": {"en-US": "Windows Hello"}, "providerLogoDark": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDI1NiAyNTYiIHZlcnNpb249IjEuMiIgYmFzZVByb2ZpbGU9InRpbnktcHMiPjx0aXRsZT5XaW5kb3dzIEhlbGxvPC90aXRsZT48ZGVmcz48L2RlZnM+PHJlY3QgeD0iMjQuMjUiIHk9IjI0LjI1IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMTMzLjQiIHk9IjI0LjI1IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMjQuMjUiIHk9IjEzMy40IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMTMzLjQiIHk9IjEzMy40IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PC9zdmc+", "providerLogoLight": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDI1NiAyNTYiIHZlcnNpb249IjEuMiIgYmFzZVByb2ZpbGU9InRpbnktcHMiPjx0aXRsZT5XaW5kb3dzIEhlbGxvPC90aXRsZT48ZGVmcz48L2RlZnM+PHJlY3QgeD0iMjQuMjUiIHk9IjI0LjI1IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMTMzLjQiIHk9IjI0LjI1IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMjQuMjUiIHk9IjEzMy40IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PHJlY3QgeD0iMTMzLjQiIHk9IjEzMy40IiB3aWR0aD0iOTguMzUiIGhlaWdodD0iOTguMzUiIGZpbGw9IiMwMDc4ZDQiIHN0cm9rZS13aWR0aD0iMHB4Ij48L3JlY3Q+PC9zdmc+" }, "a25342c0-3cdc-4414-8e46-f4807fca511c": { "friendlyNames": {"en-US": "YubiKey 5 Series with NFC", "ja-Hani-JP": "YubiKey 5 シリーズ (NFC 搭載)"}, "icon": "data:image/png;base64,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" } }
3.2. Metadata BLOB object processing rules
-
Download and cache the Convenience Metadata BLOB from the
Convenience MDS root location "c-mds.fidoalliance.org". More information can be found at https://fidoalliance.org/metadata/
The system may pass the serial number of the latest cached Convenience Metadata Service BLOB to the service (
GET /?localCopySerial=77
). In that case, the MDS will return HTTP code 304 (Not Modified) if no newer MDS blob is available. Alternatively, the serial number of the local copy could be provided through the "If-None-Match" header field. The server will always return the serial number in the ETag header field. If both, the "localCopySerial" parameter and the "If-None-Match" header are provided, the server will only process the "localCopySerial" parameter.
4. SVG requirements
This section is normative.All [SVG11] provider icons MUST adhere to the SVG Portable/Secure (SVG-P/S) profile defined in https://datatracker.ietf.org/doc/draft-svg-tiny-ps-abrotman/09/.
Additional requirements:
- Format: SVG Version: 1.2 with baseProfile as “tiny-ps"
- Elements: vector-based (cannot contain raster components)
- Dimensions: square aspect ratio
- The
<title>
element MUST be populated with the English version of the provider friendly name - The SVG MUST not contain comments or extra text
5. Considerations
This section is not normative.
This section describes the key considerations for designing this metadata service.