@animo-id/mdoc

mDOC and mDL - TypeScript

ISO 18013-5 defines mDL (mobile Driver’s Licenses): an ISO standard for digital driver licenses.

This is a JavaScript library for Node.JS, browers and React Native to issue and verify mDL CBOR encoded documents in accordance with ISO 18013-7 (draft's date: 2024-03-12).

Powered by  

Installation  |  Usage  |  Contributing  |  License  |  Credits

Installation

npm i @animo-id/mdoc

Usage

Verifying a credential

import { Verifier } from "@animo-id/mdoc";
import { inspect } from "node:util";
import fs from "node:fs";

(async () => {
  const encodedDeviceResponse = Buffer.from(encodedDeviceResponseHex, "hex");
  const encodedSessionTranscript = Buffer.from(
    encodedSessionTranscriptHex,
    "hex"
  );
  const ephemeralReaderKey = Buffer.from(ephemeralReaderKeyHex, "hex");

  const trustedCerts = [fs.readFileSync("./caCert1.pem") /*, ... */];
  const verifier = new Verifier(trustedCerts);
  const mdoc = await verifier.verify(encodedDeviceResponse, {
    ephemeralReaderKey,
    encodedSessionTranscript,
  });

  //at this point the issuer and device signature are valids.
  inspect(mdoc);
})();

Getting diagnostic information

import { Verifier } from "@animo-id/mdoc";
import { inspect } from "node:util";
import fs from "node:fs";

(async () => {
  const encodedDeviceResponse = Buffer.from(encodedDeviceResponseHex, "hex");
  const encodedSessionTranscript = Buffer.from(
    encodedSessionTranscriptHex,
    "hex"
  );
  const ephemeralReaderKey = Buffer.from(ephemeralReaderKeyHex, "hex");

  const trustedCerts = [fs.readFileSync("./caCert1.pem") /*, ... */];
  const verifier = new Verifier(trustedCerts);

  const diagnosticInfo = await verifier.getDiagnosticInformation(
    encodedDeviceResponse,
    {
      ephemeralReaderKey,
      encodedSessionTranscript,
    }
  );

  inspect(diagnosticInfo);
})();

##$ Issuing a credential

import { MDoc, Document } from "@animo-id/mdoc";
import { inspect } from "node:util";

(async () => {
  const document = await new Document("org.iso.18013.5.1.mDL")
    .addIssuerNameSpace("org.iso.18013.5.1", {
      family_name: "Jones",
      given_name: "Ava",
      birth_date: "2007-03-25",
    })
    .useDigestAlgorithm("SHA-256")
    .addValidityInfo({
      signed: new Date(),
    })
    .addDeviceKeyInfo({ deviceKey: publicKeyJWK })
    .sign({
      issuerPrivateKey,
      issuerCertificate,
    });

  const mdoc = new MDoc([document]).encode();

  inspect(encoded);
})();

##$ Generating a device response

import { DeviceResponse, MDoc } from "@animo-id/mdoc";

(async () => {
  let issuerMDoc;
  let deviceResponseMDoc;

  /**
   * This is what the MDL issuer does to generate a credential:
   */
  {
    let issuerPrivateKey;
    let issuerCertificate;
    let devicePublicKey; // the public key for the device, as a JWK

    const document = await new Document("org.iso.18013.5.1.mDL")
      .addIssuerNameSpace("org.iso.18013.5.1", {
        family_name: "Jones",
        given_name: "Ava",
        birth_date: "2007-03-25",
      })
      .useDigestAlgorithm("SHA-256")
      .addValidityInfo({
        signed: new Date(),
      })
      .addDeviceKeyInfo({ deviceKey: devicePublicKey })
      .sign({
        issuerPrivateKey,
        issuerCertificate,
        alg: "ES256",
      });

    issuerMDoc = new MDoc([document]).encode();
  }

  /**
   * This is what the DEVICE does to generate a response...
   */
  {
    let devicePrivateKey; // the private key for the device, as a JWK

    // Parameters coming from the OID4VP transaction
    let mdocGeneratedNonce, clientId, responseUri, verifierGeneratedNonce;
    let presentationDefinition = {
      id: "family_name_only",
      input_descriptors: [
        {
          id: "org.iso.18013.5.1.mDL",
          format: { mso_mdoc: { alg: ["EdDSA", "ES256"] } },
          constraints: {
            limit_disclosure: "required",
            fields: [
              {
                path: ["$['org.iso.18013.5.1']['family_name']"],
                intent_to_retain: false,
              },
            ],
          },
        },
      ],
    };

    deviceResponseMDoc = await DeviceResponse.from(issuerMDoc)
      .usingPresentationDefinition(presentationDefinition)
      .usingSessionTranscriptForOID4VP(
        mdocGeneratedNonce,
        clientId,
        responseUri,
        verifierGeneratedNonce
      )
      .authenticateWithSignature(devicePrivateKey, "ES256")
      .sign();
  }
})();

Contributing

Is there something you'd like to fix or add? Great, we love community contributions! To get involved, please follow our contribution guidelines.

License

This project is licensed under the Apache License Version 2.0 (Apache-2.0).

Credits

Thanks to:

• auth0/mdl for the mdl implementation on which this repository is based.
• auer-martin for removing node.js dependencies and providing a pluggable crypto interface

Changelog

0.3.0

Minor Changes

• 65fcc93: feat: support ISO 18013-7 Draft 2024-03-12.

  This mostly changes the structure of the calculated session transcript bytes for usage with the Web API or OpenID4VP. This is a breaking change and incompatible with older versions of this library.