Crate bhmdoc

This crate provides the functionality for handling mobile driving licenses (mDLs) and other mso_mdoc Credentials in compliance with the ISO/IEC 18013-5:2021 & ISO/IEC TS 18013-7:2024 standards, but modified to work with OpenID for Verifiable Presentations and Verifiable Credential Issuance specifications.

Details

The crate defines multiple modules, which can be roughly divided as follows.

• High-level modules: device, issuer and verifier.
• The error module describing the error values.
• Low-level data model – models.

A typical user of this crate is expected to care only about the high-level modules. The lower level data model is exposed for advanced users wishing to adapt the crate to their mso_mdoc use case.

Examples

The bhmdoc repository contains the full examples, so you should take a look there to see how things fit together.

Here we will just summarize the most common use cases of the crate.

Issuing a Mobile Driving License (mDL)

use std::str::FromStr;

use bhmdoc::models::{
    mdl::*,
    FullDate,
};

let mut rng = rand::thread_rng();
let issuer_signer = _; // Implementation of [`bh_jws_utils::Signer`]
let device_key = _; // Instance of [`bhmdoc::DeviceKey`].
let current_time = 100;

let mdl_mandatory = MDLMandatory {
    family_name: "Doe".to_owned(),
    given_name: "John".to_owned(),
    birth_date: "1980-01-02".parse().unwrap(),
    issue_date: FullDate::from_str("2024-01-01").unwrap().into(),
    expiry_date: FullDate::from_str("2029-01-01").unwrap().into(),
    issuing_authority: "MUP".to_owned(),
    issuing_country: "RH".to_owned(),
    document_number: "1234".to_owned(),
    portrait: vec![1u8, 2, 3].into(),
    driving_privileges: 7,
    un_distinguishing_sign: "sign".to_owned(),
};

let mdl = MDL::new(mdl_mandatory);

let issued = bhmdoc::Issuer
    .issue_mdl(mdl, device_key, &issuer_signer, &mut rng, current_time)
    .unwrap();

Verifying an Issued mso_mdoc Credential

let verifier = bhmdoc::Verifier::from_parts(
    "example verifier client id".to_owned(),
    "https://example.response.uri".to_owned(),
    "example nonce".to_owned(),
);

// `vp_token` as per <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html>
let vp_token = "Base64url encoded Verifiable Presentation";
let device_response = bhmdoc::models::DeviceResponse::from_base64_cbor(vp_token).unwrap();
let current_time = 100;

// This should return `Some(bh_jws_utils::SignatureVerifier)`
// based on the received `bh_jws_utils::SigningAlgorithm`.
let get_signature_verifier = |_alg| None;

let claims = verifier
    .verify(
        device_response,
        current_time,
        "example mdoc generated nonce",
        None,
        get_signature_verifier,
    )
    .unwrap();

Re-exports

pub use device::Device;

pub use error::MdocError;

pub use error::Result;

pub use issuer::Issuer;

pub use models::data_retrieval::device_retrieval::issuer_auth::DeviceKey;

pub use verifier::Verifier;

Modules

device

This module defines a Device type that works with an issued Credential.

error

This module defines the error values returned by the crate API.

issuer

This module defines the Issuer type, which is responsible for issuing mDL & other mso_mdoc Credentials in the context of OpenID for Verifiable Credential Issuance.

models

This module defines the core data types & functions used in the crate to implement the ISO/IEC 18013-5:2021 standard.

verifier

This module provides the Verifier type which is used to verify issued mDoc Credentials.

Functions

generate_nonce

Generates a nonce value.

json_to_cbor

Convert a serde_json::Value to ciborium::Value.