mDL

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

This is a Node.js library to issue and verify mDL CBOR encoded documents.

Installation

1npm i @auth0/mdl

Verifying a credential

1import { Verifier } from '@auth0/mdl';
2import { inspect } from 'node:util';
3import fs from 'node:fs';
4
5(async () => {
6  const encodedDeviceResponse = Buffer.from(encodedDeviceResponseHex, 'hex');
7  const encodedSessionTranscript = Buffer.from(
8    encodedSessionTranscriptHex,
9    'hex'
10  );
11  const ephemeralReaderKey = Buffer.from(ephemeralReaderKeyHex, 'hex');
12
13  const trustedCerts = [fs.readFileSync('./caCert1.pem') /*, ... */];
14  const verifier = new Verifier(trustedCerts);
15  const mdoc = await verifier.verify(encodedDeviceResponse, {
16    ephemeralReaderKey,
17    encodedSessionTranscript,
18  });
19
20  //at this point the issuer and device signature are valids.
21  inspect(mdoc);
22})();

Getting diagnostic information

1import { Verifier } from '@auth0/mdl';
2import { inspect } from 'node:util';
3import fs from 'node:fs';
4
5(async () => {
6  const encodedDeviceResponse = Buffer.from(encodedDeviceResponseHex, 'hex');
7  const encodedSessionTranscript = Buffer.from(
8    encodedSessionTranscriptHex,
9    'hex'
10  );
11  const ephemeralReaderKey = Buffer.from(ephemeralReaderKeyHex, 'hex');
12
13  const trustedCerts = [fs.readFileSync('./caCert1.pem') /*, ... */];
14  const verifier = new Verifier(trustedCerts);
15
16  const diagnosticInfo = await verifier.getDiagnosticInformation(
17    encodedDeviceResponse,
18    {
19      ephemeralReaderKey,
20      encodedSessionTranscript,
21    }
22  );
23
24  inspect(diagnosticInfo);
25})();

Issuing a credential

1import { MDoc, Document } from '@auth0/mdl';
2import { inspect } from 'node:util';
3import fs from 'node:fs';
4
5(async () => {
6  const document = await new Document('org.iso.18013.5.1.mDL')
7    .addIssuerNameSpace('org.iso.18013.5.1', {
8      family_name: 'Jones',
9      given_name: 'Ava',
10      birth_date: '2007-03-25',
11    })
12    .useDigestAlgorithm('SHA-256')
13    .addValidityInfo({
14      signed: new Date(),
15    })
16    .addDeviceKeyInfo({ deviceKey: publicKeyJWK })
17    .sign({
18      issuerPrivateKey,
19      issuerCertificate,
20    });
21
22  const mdoc = new MDoc([document]).encode();
23
24  inspect(encoded);
25})();

Generating a device response

1import { DeviceResponse } from "@auth0/mdl";
2(() => {
3  let issuerMDoc;
4  let deviceResponseMDoc;
5
6  // This is what the MDL issuer does to generate a credential:
7  {
8    const document = await new Document('org.iso.18013.5.1.mDL')
9      .addIssuerNameSpace('org.iso.18013.5.1', {
10        family_name: 'Jones',
11        given_name: 'Ava',
12        birth_date: '2007-03-25',
13      })
14      .useDigestAlgorithm('SHA-256')
15      .addValidityInfo({
16        signed: new Date(),
17      })
18      .addDeviceKeyInfo({ deviceKey: publicKeyJWK })
19      .sign({
20        issuerPrivateKey,
21        issuerCertificate,
22        alg: 'ES256',
23      });
24    issuerMDoc = new MDoc([document]).encode();
25  }
26
27  // This is what the DEVICE does to generate a response:
28  {
29    deviceResponseMDoc = await DeviceResponse.from(issuerMDoc)
30      .usingPresentationDefinition(PRESENTATION_DEFINITION_1)
31      .usingHandover([mdocGeneratedNonce, clientId, responseUri, verifierGeneratedNonce])
32      .authenticateWithSignature(devicePrivateKey, 'ES256')
33      .sign();
34  }
35})();

License

Apache-2.0