U2F JSON metadata format specification

Note
This is not part of the U2F standard. For a background, see Attestation and Metadata.

Attestation and metadata is provided as MetadataObjects, as defined in this document. These objects might be stored as files in a file system (one object per file), a single file (containing a list of multiple objects), as data in a database, or any combination thereof.

MetadataObject

dictionary MetadataObject {
  DOMString identifier;
  unsigned long version;
  DOMString[] trustedCertificates;
  optional VendorInfo vendorInfo;
  optional DeviceInfo[]? devices;
}

The metadata object is uniquely identified by the identifier property, which MUST be globally unique. The version property identifies the version of the object, with higher versions being newer. The trustedCertificates property consists of a list of PEM encoded certificates that are trusted for attestation certificate validation. Intermediate certificates may be present in the chain, between one of the trusted certificates and the attestation certificates, but how these certificates are provided is outside of the scope for this document. A certificate in the trustedCertificates list is trusted, and its own signature is not regarded (whether it be self-signed or not). The devices property is optional, and used to provide metadata about different device types.

VendorInfo

dictionary VendorInfo {
  DOMString name;
  DOMString url;
  DOMString imageUrl;
}

The vendor info object contains information about the vendor, such as name and URL. Additional fields may be added to provide more information.

DeviceInfo

dictionary DeviceInfo {
  DOMString deviceId;
  optional DOMString displayName;
  optional DOMString imageUrl;
  optional DOMString deviceUrl;
  optional unsigned long transports;
  optional Selector[] selectors;
}

The device object provides metadata for a U2F device model. The deviceId is a unique identifier for a U2F device model, which can be used to update previously identified devices if the metadata changes. Additional fields may be added to provide more information. The selector is used to match a device object to a given attestation certificate. When not present, the device will match any certificate as long as it is trusted by one of the roots from the same metadata object.

Selector

dictionary Selector {
  DOMString type;
  optional dictionary parameters;
}

The selector object provides a way to match an attestation certificate against a device object. When present in a device object, each supported selector type is tested against the attestation certificate. If any of them match, the device matches. If none of the selectors match, the device does not match. An empty selectors list [], cannot be matched by any attestation certificate. However, a null or missing selectors field is matched by any certificate.

Selector types

The selector type is defined by the string in the type field. The parameters field is type dependent and can contain arbitrary data.

Fingerprint

Match certificates by their SHA1 fingerprint.

Type value

fingerprint

Parameters type

dictionary FingerprintParameters {
  DOMString[] fingerprints;
}

The fingerprints field contains hex values of SHA1 fingerprints of attestation certificates to match against.

x509Extension

Match certificates by their extensions.

Type value

x509Extension

Parameters type

dictionary X509ExtensionParameters {
  DOMString key;
  optional DOMString value;
}

The key field contains the textual representation of the OID of the extension to match against. The value field contains the matching value when compared to the extensions OctetString value when interpreted as an ASCII string. If the value field is missing, any value will be accepted, as long as the certificate has the extension with the given key.

Transports

If present, the transports value in the DeviceInfo indicates the available U2F transports for the device. Each bit in the value represents a transport, with the value of 1 indicating that the transport is available.

Transport bit definitions

Bluetooth Classic

0x01

Bluetooth LE

0x02

USB

0x04

NFC

0x08

For example, a transport value of 12 (0b00001100 in binary) indicates that the device has both USB and NFC interfaces.