Skip to main content
Version: v0.10

intro

Currently, the Mdoc SDK supports the following device engagement methods:

  • QR
  • NFC tag
  • URI (reverse) engagement

and the retrieval (transfer) is done via:

  • Bluetooth Low Energy (BLE)
  • NFC (not recommended)
  • ISO 18013-7 REST API
  • ISO 18013-7 OID4VP protocol

Quick outline of the below process​

Given the engagement and transfer of mdocs can happen via multiple transports and transmission protocols, we will first give a quick summary. The process is defined in the ISO 18013-5 and 18013-7 specifications.

  • You will first start the engagement process, typically either via a QR code or via NFC. The mdoc holder by default generates the QR code, so the recipient can scan it.
  • The engagement manager is responsible for creating a new engagement instance. The instance returns all the information about the specific engagement
  • At this point the engagement is not started yet. Meaning no connections are made yet. You will need to call start() on the engagement instance.
  • One or more retrieval (transfer) methods will now be enabled. This allows the external Relying Party (mdoc reader) to connect to your device. Via BLE, NFC, or you connect via HTTPS (reverse)
  • The mdoc reader will connect via one of the supported methods. The other methods will be automatically closed by the mdoc holder device at this point as these apparently will not be used. As soon as one of the methods is being used, the state will move to CONNECTING.
  • The transfer connection is being setup until the CONNECTED state is reached.
  • The Relying Party (mdoc reader) will send a session establishment message to the mdoc holder device. It contains a Device Request object
  • The Device Request object's main responsibility is expressing which mdoc/mdoc document(s) the Relying Party would like to receive and which claims to receive.
  • The mdoc holder device now will perform matching of the available mdocs against the requested document(s), typically including the user in this process to both validate and approve the data transmission of the claims
  • The mdoc holder device now will create a Device Response object, encrypt it into a SessionData object, and send it back to the Relying Party.
  • The transfer session will be terminated successfully, and all connections will be closed.

QR Engagement​

QR engagement means you will generate and show a QR code to the remote party. This QR code contains information about the retrieval methods supported, like BLE and NFC. It also contains a unique value used by the other party to set up the connection for the transfer/retrieval phase.

NFC Engagement​

NFC engagement means you will be able to tap your device to a remote mdoc reader device or terminal operated by the Relying Party. NFC engagement can either be started and enabled on application startup, so it is always available, or it can be started on demand. Meaning it will only be enabled once the init method is being called with nfc as one of its arguments.

URI (reverse) Engagement​

Reverse engagement is defined in ISO 18013-7 and basically means that the other side generates an mdoc URI, that you will use. So similar to the QR code being generated above which in turn contains an mdoc URI, now you recieve a URI in the app from the reader. It contains the following information:

  • URI starts with “mdoc://”
  • Followed by the reader Engagement data encoded base64 url-without-padding

The SDK interprets the engagement data instead of generating the engagement data, hence why it is called reverse engagement. Typically this also involves ReaderEngagement data being interpreted by the mdoc holder, instead of starting with DeviceEngagement data from the mdoc holder.

How the reverse engagement reaches the holder (mdoc) device is not really important. Could be a QR code, could even be a link via a website or e-mail. If it is not a QR code your app should be able to handle the URI that starts with the mdoc:// scheme. We provide limited information below. Please consult the respective platform documentation on how to handle the actual URLs in your code. The idea is that you would call the engagement manager explained below using the uri option, once you receive a URL.

For instance for Android apps you would have to declare the intent filter in your app's manifest file (AndroidManifest.xml) for your MainActivity:

<intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="mdoc" android:host="*"/>
</intent-filter>
info

On android set launchMode="singleTask" for the activity.

note

The above talks about the ISO 18013-7 reverse engagement using the scheme mdoc://. There is another protocol that is also supported, called OID4VP. That protocol uses a similar scheme, called mdoc-openid4vp://. The above notes about intents and mobile platform support also applies for this scheme. If you want to support both, then both should be configured properly for your app.