WebAuthn/FIDO2: What’s new in MDS3? Migrating from MDS2 to MDS3.

Published in

WebAuthn Works

5 min readMay 26, 2021

It’s a JSON! It looks like MDS2? Nope, that’s MDS3!

This is continuation of our series on Webauthn and FIDO2.

Recently FIDO Alliance released new version of the metadata specification. And it’s not simple added new fields, and called it day.

MDS3 Metadata entirely overhauled schema, deleting old fields, merging some and replacing numerical and flags with strings, in addition to the major improvements for Metadata Service.

Changes to Metadata Service

First, and the most important thing: YOU NO LONGER NEED ACCESS TOKEN TO ACCESS MDS.

You can find all the access info on the FIDO Alliance website: https://fidoalliance.org/metadata/

Second, nor less important thing: YOU NO LONGER NEED TO DOWNLOAD HUNDREDS OF FILES! ALL METADATA COMES AS ONE BLOB! HALLELUJAH!

Big shout-out to Hideez Group Inc for the service they’ve built.

Regarding Metadata Service it self:

Completely overhauled UI. One place to submit metadata, request certification, add new root certificates, submit security notification, etc.

Direct integration with conformance tools. Now when you complete conformance testing, you can select your metadata to be submitted to your account.
Enterprise security features: Event logging accessible by the vendors to see what actions happened. Mandatory FIDO MFA. Ability to manage teams, for large vendors.
Daily on-demand updates. You no longer need to wait for a month for you metadata to be submitted.
MDS BLOB is now CDN backed for better availability.
PKI by GlobalSign!
Multi-lingual support.

Here is decode BLOB sample:

{
  "no": 1234,
  "nextUpdate": "2014-03-31",
  "entries": [
    {
      "aaid": "1234#5678",
      // Metadata Statement Object https://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html#metadata-statement-format
      "metadataStatement": {"aaid": "1234#5678"...},
      "statusReports": [
        {
          "status": "FIDO_CERTIFIED",
          "effectiveDate": "2014-01-04"
        }
      ],
      "timeOfLastStatusChange": "2014-01-04"
    },
    {
      "attestationCertificateKeyIdentifiers": [
        "7c0903708b87115b0b422def3138c3c864e44573"
      ],
      // Metadata Statement Object https://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html#metadata-statement-format
      "metadataStatement": {"attestationCertificateKeyIdentifiers": ["7c0903708b87115b0b422def3138c3c864e44573"]...},
      "statusReports": [
        {
          "status": "FIDO_CERTIFIED",
          "effectiveDate": "2014-01-07"
        },
        {
          "status": "UPDATE_AVAILABLE",
          "effectiveDate": "2014-02-19",
          "url": "https://example.com/update1234"
        }
      ],
      "timeOfLastStatusChange": "2014-02-19"
    }
  ]
}

You can find more in depth info in the latest publication of Metadata Service spec: https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html

Changes to Metadata Statement

Numerical fields became string:

WAS: "userVerificationDetails": [[{ "userVerification": 2 }]]NOW: "userVerificationDetails": [[{ "userVerificationMethod": "fingerprint_internal" }]]-------------------------------------------------------------WAS: "keyProtection": 6NOW: "keyProtection": ["hardware", "tee"]

This applies to authenticationAlgorithms, publicKeyAlgAndEncodings, attestationTypes, userVerificationDetails, keyProtection, matcherProtection, attachmentHint, tcDisplay

2. Major cleanup:

Removed: assertionScheme, authenticationAlgorithm, publicKeyAlgAndEncoding, operatingEnv, isSecondFactorOnly
authenticationAlgorithms replaced authenticationAlgorithm
publicKeyAlgAndEncodings replaced publicKeyAlgAndEncoding

3. New fields:

schema — Numerical identifier of the schema. Use this to check if you are dealing with old or new metadata.
authenticatorGetInfo — Snapshot of authenticatorGetInfo. Relying parties can use it to make informed decisions about FIDO2 authenticators.

{
  "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
  "description": "FIDO Alliance Sample FIDO2 Authenticator",
  "aaguid": "0132d110-bf4e-4208-a403-ab4f5f12efe5",
  "alternativeDescriptions": {
      "ru-RU": "Пример FIDO2 аутентификатора от FIDO Alliance",
      "fr-FR": "Exemple FIDO2 authenticator de FIDO Alliance",
      "zh-CN": "來自FIDO Alliance的示例FIDO2身份驗證器"
  },
  "protocolFamily": "fido2",
  "schema": 3,
  "authenticatorVersion": 5,
  "upv": [
    { "major": 1, "minor": 0 }
  ],
  "authenticationAlgorithms": ["secp256r1_ecdsa_sha256_raw", "rsassa_pkcsv15_sha256_raw"],
  "publicKeyAlgAndEncodings": ["cose"],
  "attestationTypes": ["basic_full"],
  "userVerificationDetails": [
    [
      {"userVerificationMethod": "none"}
    ],
    [
     {"userVerificationMethod": "presence_internal"}
    ],
    [{
      "userVerificationMethod": "passcode_external",
      "caDesc": { 
        "base": 10,
        "minLength": 4
      }
    }],
    [{
      "userVerificationMethod": "passcode_external",
      "caDesc": { 
        "base": 10,
        "minLength": 4
     }},
     {"userVerificationMethod": "presence_internal"}
    ]
  ], 
  "keyProtection": ["hardware", "secure_element"],
  "matcherProtection": ["on_chip"],
  "cryptoStrength": 128,
  "attachmentHint": ["external", "wired", "wireless", "nfc"],
  "tcDisplay": [],
  "attestationRootCertificates": [
    "MIICPTCCAeOgAwIBAgIJAOuexvU3Oy2wMAoGCCqGSM49BAMCMHs..."
  ],
  "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAE8A...",
  "supportedExtensions": [
    {
      "id": "hmac-secret",
      "fail_if_unknown": false
    },
    {
      "id": "credProtect",
      "fail_if_unknown": false
    }
  ],
  "authenticatorGetInfo": {
      "versions": [ "U2F_V2", "FIDO_2_0" ],
      "extensions": [ "credProtect", "hmac-secret" ],
      "aaguid": "0132d110bf4e4208a403ab4f5f12efe5",
      "options": {
        "plat": false,
        "rk": true,
        "clientPin": true,
        "up": true,
        "uv": true,
        "uvToken": false,
        "config": false
      },
      "maxMsgSize": 1200,
      "pinUvAuthProtocols": [1],
      "maxCredentialCountInList": 16,
      "maxCredentialIdLength": 128,
      "transports": ["usb", "nfc"],
      "algorithms": [{
          "type": "public-key",
          "alg": -7
        },
        {
          "type": "public-key",
          "alg": -257
        }
      ],
      "maxAuthenticatorConfigLength": 1024,
      "defaultCredProtect": 2,
      "firmwareVersion": 5
  }
}

You can find out more from reading latest spec: https://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html

What about legacy MDS2?

Legacy MDS2 have been deprecated. PKI updated to the GlobalSign. No new metadata will be added there and it will be shutdown in 18 months, or in October 2022. You can find more information about it here https://fidoalliance.org/legacy-mds2-information/

Relying parties should start planning moving to MDS3 quiet soon, and our guide will help you just do that. You

Migrating to MDS3

First I would like to clarify implication for certified servers. If you update your code to support MDS3, and then run conformance tests, your certification will not be affected.

FIRST: The processing rules for new BLOB have not changed that much. JWT, certificate, and CRL validation are exactly the same. So you basically need to delete all of the individual metadata download code, and return entry.metadataStatement, since this is where the metadata object is now located.

One thing that I might note here is that GlobalSign is now returning CRL not in PEM, but as bytes, with content type “application/pkix-crl” so you might need to adjust your CRL validation code.

If your solutions is downloading root certificates on-demand, please ensure that you add root certificate directly to your code, or certificate storage.

SECOND: Import latest registry. FIDO Alliance kindly provides registry as JS dictionaries that can be easily convert to what ever ENUM you need https://github.com/fido-alliance/conformance-test-tools-resources/blob/master/snippets/registry.js

THIRD: Update your code to work with new SHORT string constant:

For attestationTypes:

For packed and fido-u2f check that attestation types contains “basic_full” or “basic_surrogate” in case of FIDO2 self attestation.
For tpm check that attestation types contain “attca”
For apple, apple-appattest, safety-net, android-key check that attestation types contain “anonca”

For authenticationAlgorithms and publicKeyAlgAndEncodings:

Singular authenticationAlgorithm and publicKeyAlgAndEncoding were removed and only plural authenticationAlgorithmS and publicKeyAlgAndEncodingS are left
You can find latest mapping between COSE to ALG in COSE_PARAM_TO_FIDO_ALG_SHORT dictionary https://github.com/fido-alliance/conformance-test-tools-resources/blob/master/snippets/registry.js#L1079

For UAF: tcDisplay is now a list of short for flags, like: [“any”, “tee“]. tcDisplayContentType and tcDisplayDisplayPNGCharacteristics.

FOURTH: Version 3 Metadata now contains “schema” field with value 3. Using that you can easily distinguish old and new schema in the mixed MDS environments.

FIFTH: Apple Anonymous Attestation is now mandatory. You can find how to validate it in my recent article https://medium.com/webauthnworks/webauthn-fido2-verifying-apple-anonymous-attestation-5eaff334c849

Resources

FIDO Alliance official info on MDS — https://fidoalliance.org/metadata/
Metadata Statement 3 — https://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html
Metadata Service 3 — https://fidoalliance.org/specs/mds/fido-metadata-service-v3.0-ps-20210518.html
Latest Registry in JS —https://github.com/fido-alliance/conformance-test-tools-resources/blob/master/snippets/registry.js
Verifying Apple Anonymous Attestation — https://medium.com/webauthnworks/webauthn-fido2-verifying-apple-anonymous-attestation-5eaff334c849

License

This article is licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0). So you are free to read, share, etc. If you are interested in commercial use of this article, or wish to translate it to a different language, please contact us at info(at)webauthn(dot)works

The code samples are licensed under MIT license.