Skip to main content
Version: v0.13

Mobile Credentials (mDoc) Overview

The IDK implements ISO/IEC 18013-5 for mobile driving licenses (mDL) and mobile credentials (mDoc). This standard defines how to store, present, and verify identity credentials on mobile devices using secure, privacy-preserving protocols.

What is mDoc?​

An mDoc (mobile document) is a digital credential stored on a mobile device that can be presented to verifiers through close-range communication technologies like NFC and Bluetooth. The ISO 18013-5 standard was originally designed for mobile driving licenses but has been adopted for other credential types.

Key characteristics of mDoc:

  • Offline verification: Credentials can be verified without an internet connection
  • Selective disclosure: Holders can share only specific attributes, not the entire credential
  • Cryptographic security: Issuer signatures and device authentication prevent tampering
  • Privacy preserving: Reader authentication ensures credentials are only shared with legitimate verifiers

Protocol Flow​

The mDoc presentation protocol consists of two main phases:

Phase 1: Engagement​

During engagement, the holder and verifier establish how they will communicate. The holder's device generates engagement data containing:

  • A device engagement structure with transport options
  • An ephemeral public key for establishing the session

This engagement data is transmitted out-of-band through:

  • QR code: The holder displays a QR code that the verifier scans
  • NFC tap: The holder taps their device on the verifier's reader
  • TO_APP (mdoc://): App-to-app reverse engagement for ISO 18013-7

Phase 2: Data Transfer​

Once engaged, the actual credential exchange occurs:

  1. Reader request: The verifier sends a DeviceRequest specifying which data elements are needed
  2. User consent: The holder reviews the request and approves sharing
  3. Device response: The holder's device creates a signed DeviceResponse with the requested data
  4. Verification: The verifier validates signatures and trust chains

IDK Components​

The IDK provides several components for implementing mDoc functionality:

MdocEngagementManager​

The central entry point for mDoc operations. It manages the complete lifecycle from engagement through data transfer.

val engagementManager = session.component.mdocEngagementManager

// Access engagement instances
val qrEngagement = engagementManager.qrEngagement     // StateFlow<EngagementInstance?>
val nfcEngagement = engagementManager.nfcEngagement   // StateFlow<EngagementInstance?>
val toAppEngagement = engagementManager.toAppEngagement // StateFlow<EngagementInstance?>

// Access event hub for UI integration
val eventHub = engagementManager.eventHub

See the Engagement Manager guide for details.

TransferManager​

Handles the data transfer phase after engagement is established. Manages device requests and responses.

// Start engagement to get transfer manager
val transferManager = engagementInstance.start()

// Receive and respond to requests
val deviceRequest = transferManager.receiveDeviceRequest()
val deviceResponse = transferManager.createResponse(deviceRequest, documentProvider)
transferManager.sendDeviceResponse(deviceResponse)

See the Transfer Manager guide for details.

Transport Layer​

The IDK supports multiple transports for the data transfer phase:

TransportUse Case
BLE (Bluetooth Low Energy)Common for mobile-to-mobile presentation
NFCQuick tap-and-go scenarios
REST API / WebsiteRemote or server-based verification
OID4VPIntegration with OpenID4VP presentation flows
WiFi AwareDirect device-to-device WiFi connections

See the Transports guides for configuration details.

Engagement Types​

The IDK supports three engagement types:

TypeStandardURI SchemeDescription
QRISO 18013-5mdoc: (opaque)QR code displayed by holder
NFCISO 18013-5N/ANFC tap proximity engagement
TO_APPISO 18013-7mdoc:// or mdoc-openid4vp://App-to-app reverse engagement

URI Scheme Patterns​

The toApp() method supports three URI patterns:

  • mdoc: (opaque, no slashes): Classic reverse engagement with BLE/NFC
  • mdoc:// (hierarchical, with slashes): REST API / Website retrieval
  • mdoc-openid4vp://: OID4VP with OAuth 2.0 integration

Credential Structure​

An mDoc credential consists of:

IssuerSigned Data​

Data signed by the credential issuer:

  • Mobile Security Object (MSO): Contains digests of all data elements, signed by the issuer
  • Namespaces: Data elements organized by namespace (e.g., org.iso.18013.5.1 for mDL)
  • Issuer certificate chain: X.509 certificates establishing trust
// IssuerSigned structure
data class IssuerSigned(
    val nameSpaces: IssuerSignedNameSpaces?,
    val issuerAuth: COSE_Sign1<MobileSecurityObject>
) {
    val MSO: MobileSecurityObject  // Mobile Security Object
    val deviceKeyInfo: DeviceKeyInfoCbor  // Device key from MSO

    fun getNameSpaces(): Set<NameSpace>
    fun getIssuerSignedItems(ns: String): List<IssuerSignedItem<Any>>?
    fun limitDisclosures(docRequest: DocRequest): IssuerSigned
}

DeviceSigned Data​

Data signed by the holder's device during presentation:

  • Session transcript: Cryptographic binding to the current session
  • Device authentication: Proves the holder controls the device key
// DeviceSigned structure
data class DeviceSigned(
    val nameSpaces: DeviceNameSpaces,
    val deviceAuth: DeviceAuth
)

Data Elements​

Data elements are individual attributes within a credential. For an mDL, typical elements include:

ElementNamespaceDescription
family_nameorg.iso.18013.5.1Holder's family name
given_nameorg.iso.18013.5.1Holder's given name
birth_dateorg.iso.18013.5.1Date of birth
portraitorg.iso.18013.5.1Photo of the holder
document_numberorg.iso.18013.5.1License number
driving_privilegesorg.iso.18013.5.1License categories
issue_dateorg.iso.18013.5.1When the license was issued
expiry_dateorg.iso.18013.5.1When the license expires
age_over_18org.iso.18013.5.1Age attestation claim
age_over_21org.iso.18013.5.1Age attestation claim

Security Model​

mDoc security relies on several layers:

Issuer Trust​

The credential issuer signs the MSO with their private key. Verifiers validate this signature against a trust anchor (typically a certificate from a trusted authority).

Device Binding​

The credential is bound to a specific device through a device key. During issuance, the device generates a key pair and the public key is included in the MSO. During presentation, the device proves possession of the private key.

Session Encryption​

All communication after engagement is encrypted using keys derived from the ephemeral key exchange. This prevents eavesdropping and man-in-the-middle attacks.

Reader Authentication​

Optionally, holders can require verifiers to prove their identity before sharing data. This prevents credential harvesting by unauthorized parties.

Getting Started​

To implement mDoc functionality in your application:

  1. Set up the Engagement Manager for holder or verifier roles
  2. Configure appropriate transports for your use case
  3. Handle events to build responsive UIs
  4. Implement the data transfer flow for actual credential exchange