Engagement Concepts

Engagement is the first phase of the ISO 18013-5 protocol where the holder's device and the verifier establish how they will communicate. This phase happens before any credential data is exchanged.

What is Engagement?

Engagement serves two purposes:

1. Transport negotiation: Both parties agree on which communication channel to use (BLE, NFC, HTTP)
2. Key exchange: Both parties exchange ephemeral public keys to establish an encrypted session

The engagement phase uses "out-of-band" communication, meaning it happens through a different channel than the main data transfer. Common out-of-band methods include QR codes, NFC taps, and app-to-app deep links.

Device Engagement Structure

The holder's device creates a device engagement structure containing:

DeviceEngagement = {
    version: "1.0",
    security: [
        ephemeralPublicKey,
        keyAgreementProtocol
    ],
    deviceRetrievalMethods: [
        bleOptions,
        nfcOptions,
        wifiOptions
    ]
}

This structure is CBOR-encoded and transmitted to the verifier. The verifier parses it to determine which transports are available and to obtain the device's ephemeral public key.

Engagement Types

The IDK supports three engagement types:

Type	Standard	Description
QR	ISO 18013-5	QR code displayed by holder for verifier to scan
NFC	ISO 18013-5	NFC tap proximity engagement
TO_APP	ISO 18013-7	App-to-app reverse engagement via deep links

QR Code Engagement

The holder displays a QR code containing the device engagement. The verifier scans this QR code to begin the session.

This method is widely supported and works well for in-person verification where the verifier has a camera. The QR code is dynamic, generated for each session.

NFC Engagement

The holder taps their device on an NFC reader. The device engagement is transmitted via NFC Data Exchange Format (NDEF).

NFC engagement provides a quick, intuitive interaction but requires both devices to support NFC.

TO_APP Engagement (Reverse Engagement)

For app-to-app flows per ISO 18013-7, the verifier initiates by sending a deep link to the holder's wallet app. The URI schemes supported are:

Scheme	Description
mdoc: (opaque)	Classic reverse engagement with BLE/NFC
mdoc:// (hierarchical)	REST API / Website retrieval
mdoc-openid4vp://	OID4VP with OAuth 2.0 integration

Session Establishment

After the verifier receives the device engagement:

1. Key agreement: The verifier generates its own ephemeral key pair and derives shared secrets using ECDH
2. Session transcript: Both parties compute the session transcript, a cryptographic binding of the engagement parameters
3. Encryption keys: Session encryption keys are derived from the shared secrets
4. Transport connection: The actual data channel (BLE, NFC, etc.) is established

All subsequent communication is encrypted using the derived keys.

Session Transcript

The session transcript is critical for security. It binds the device response to this specific session, preventing replay attacks. The transcript includes:

• Device engagement bytes
• Reader engagement bytes (if any)
• Handover data (for NFC/QR handover scenarios)

Both parties must compute identical transcripts for verification to succeed.

Engagement Lifecycle

Engagement Instance Lifecycle States

Engagements progress through these states:

State	Description
INITIALIZING	Engagement is being set up
CONNECTING	Establishing transport connection
CONNECTED	Transport connected, ready for transfer
TRANSFERRING	Data exchange in progress
COMPLETED	Transfer completed successfully
ERROR	An error occurred

Next Steps

• Learn how to use the Engagement Manager to create and manage engagements
• Understand different retrieval methods for data transfer
• Handle events to build responsive UIs