@animo-id/mdoc
v0.2.39
Published
Animo Mdoc and MDL
Downloads
2,913
Readme
ISO 18013-5 defines mDL (mobile Driver 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: 2023-08-02).
Installation
npm i @animo-id/mdoc
Usage
Verifying a credential
import { Verifier } from "@auth0/mdl";
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 "@auth0/mdl";
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 "@auth0/mdl";
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 "@auth0/mdl";
(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