{"id":23746315,"url":"https://github.com/spruceid/isomdl","last_synced_at":"2025-10-30T13:11:59.602Z","repository":{"id":200173752,"uuid":"475478037","full_name":"spruceid/isomdl","owner":"spruceid","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-18T12:08:56.000Z","size":832,"stargazers_count":6,"open_issues_count":38,"forks_count":8,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-12-18T12:39:26.582Z","etag":null,"topics":["mdl"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spruceid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-29T14:23:02.000Z","updated_at":"2024-11-21T17:58:12.000Z","dependencies_parsed_at":"2023-12-20T17:26:57.046Z","dependency_job_id":"6d4094a0-c6c2-4bf7-8980-1cea73d8ce90","html_url":"https://github.com/spruceid/isomdl","commit_stats":null,"previous_names":["spruceid/isomdl"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spruceid%2Fisomdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spruceid%2Fisomdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spruceid%2Fisomdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spruceid%2Fisomdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spruceid","download_url":"https://codeload.github.com/spruceid/isomdl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231991717,"owners_count":18457111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mdl"],"created_at":"2024-12-31T13:34:34.777Z","updated_at":"2025-10-30T13:11:54.550Z","avatar_url":"https://github.com/spruceid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# isomdl\n\n[ISO/IEC DIS 18013-5](https://www.iso.org/standard/69084.html) `mDL` implementation in Rust.\n\nIt is intended to be used in creating apps for devices and readers that can interact with each other to exchange `mDL`\ndata.\n\n## CLI tool\n\nThis crate contains a CLI tool. Run the `--help` command to see what actions you can perform.\n\n```bash\ncargo run -- --help\n```\n\nFor example, you can get the namespaces and elements defined in an mDL:\n\n```bash\ncat test/stringified-mdl.txt | cargo run -- get-namespaces -\n```\n\n## Library\n\nHere are some examples on how to use the library.\nYou can see more in [tests](tests) and read about in the\ndedicated [README](tests/README.md).\n\n### Examples\n\n#### Simulated device and reader interaction\n\nThis example demonstrates a simulated device and reader interaction.  \nThe reader requests the `age_over_21` element, and the device responds with that value.\n\n```mermaid\nsequenceDiagram\n    autonumber\n    Note over Device: Initialize session\n    Device -\u003e\u003e Device: Create QR Code Engagement\n    Device -) + Reader: Send QR Code\n    Reader -\u003e\u003e - Reader: Establish Session\n    Reader -) + Device: Request age_over_21\n    Device -)- Reader: Send age_over_21\n    Reader -\u003e\u003e Reader: Process age_over_21\n    Note over Device, Reader: Session finished\n```\n\n### The flow of the interaction\n\n1. **Device initialization and engagement:**\n    - The device creates a `QR code` containing `DeviceEngagement` data, which includes its public key.\n    - Internally:\n        - The device initializes with the `mDL` data, private key, and public key.\n2. **Reader processing QR code and requesting needed fields:**\n    - The reader processes the `QR code` and creates a request for the `age_over_21` element.\n    - Internally:\n        - Generates its private and public keys.\n        - Initiates a key exchange, and generates the session keys.\n        - The request is encrypted with the reader's session key.\n3. **Device accepting request and responding:**\n    - The device receives the request and creates a response with the `age_over_21` element.\n    - Internally:\n        - Initiates the key exchange, and generates the session keys.\n        - Decrypts the request with the reader's session key.\n        - Parse and validate it creating error response if needed.\n        - The response is encrypted with the device's session key.\n4. **Reader Processing mDL data:**\n    - The reader processes the response and prints the value of the `age_over_21` element.\n\n##### Device perspective\n\nThere are several states through which the device goes during the interaction:\n\n```mermaid\nstateDiagram\n    state Device {\n        [*] --\u003e SessionManagerInit: initialise\n        SessionManagerInit --\u003e SessionManagerEngaged: qr_engagement\n        SessionManagerEngaged --\u003e SessionManager: process_session_establishment\n    }\n\n    state SessionManagerInit {\n        [*] --\u003e [*]\n    }\n\n    state SessionManagerEngaged {\n        [*] --\u003e [*]\n    }\n\n    state Reader {\n        [*] --\u003e [*]\n    }\n\n    state SessionManager {\n        [*] --\u003e AwaitingRequest\n        AwaitingRequest --\u003e Signing: prepare_response\n        Signing --\u003e Signing: get_next_signature_payload\n        Signing --\u003e ReadyToRespond: submit_next_signature\n        ReadyToRespond --\u003e AwaitingRequest: retrieve_response\n        AwaitingRequest --\u003e Signing: handle_request\n    }\n\n    User --\u003e Device\n    SessionManagerInit --\u003e Reader: qr_engagement\n    Reader --\u003e SessionManagerEngaged: establish_session\n    ReadyToRespond --\u003e Reader: handle_response\n```\n\n##### Reader perspective\n\nFrom the reader's perspective, the flow is simpler:\n\n```mermaid\nstateDiagram\n    state Device {\n        [*] --\u003e [*]\n    }\n\n    state Reader {\n        SessionManager --\u003e SessionManager: handle_response\n    }\n\n    User --\u003e Device\n    Device --\u003e Reader: qr_engagement\n    Reader --\u003e Device: establish_session\n    Device --\u003e Reader\n    Reader --\u003e Device: new_request\n```\n\n### Example\n\nYou can see the full example in [simulated_device_and_reader](tests/simulated_device_and_reader.rs) and a version that\nuses `State` pattern, `Arc` and `Mutex` [simulated_device_and_reader](tests/simulated_device_and_reader_state.rs).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspruceid%2Fisomdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspruceid%2Fisomdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspruceid%2Fisomdl/lists"}