mDocs Verifier SDK

Overview

The mDocs verifier SDK is based on the ISO/IEC 18013-5:2021 standard which establishes an interoperable digital representation for mobile based credentials such as mobile drivers licenses (mDL). However, this SDK is designed to work for more then just mDLs, but rather any conforming mobile document (mDoc) - a term defined in ISO/IEC 18013-5:2021.

The general responsibilities of the SDK can be summarized as the following:

Manage a list of trusted issuer certificates which presented mDocs can be validated against.
Interface with a holder to request presentations of issued mDocs as per ISO/IEC 18013-5:2021.
Manage a list of mDocs status lists which is used to check the revocation status.

In this SDK mDocs are referred to as Mobile Credentials.

Supported ISO/IEC 18013-5 Features

ISO/IEC 18013-5:2021 as a standard contains many different features, some of which are not currently supported by this SDK. Below is a summary of supported features:


Feature	Options Supported	Default Option Selected
Device Engagement	QR Code-based and NFC	QR Code-based
Device Retrieval Data Transport	BLE-based with mDocPeripheralServer and mDocCentralClient mode	BLE-based using mDocPeripheralServer
Ephemeral Session Key Curve	NIST P-\*-based keys	P-256-based key using Secure Enclave
Device Authentication Mode	Both Digital Signature and ECDH-agreed MAC	Digital Signature, P-256-based key using Secure Enclave

System requirements

This SDK is developed in the Kotlin programming language and is meant for integration into Android applications. It currently supports Android 7 (API level 24) and above. The SDK is compiled using API level 35.

Gradle version used to build the project: 8.7 AGP version used to build the project: 8.6.1 JVM target version: 1.8

Library dependencies

A set of external libraries was used to build the SDK.

Standard libraries

androidx.core:core-ktx:1.13.1
androidx.appcompat:appcompat:1.7.0
androidx.activity:activity-ktx:1.9.0
androidx.fragment:fragment:1.5.4
androidx.annotation:annotation:1.8.0
androidx.biometric:biometric-ktx:1.2.0-alpha05
androidx.browser:browser:1.8.0
org.jetbrains.kotlin:kotlin-reflect:1.9.22
org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3
org.jetbrains.kotlinx:kotlinx-datetime:0.4.0
org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3
org.jetbrains.kotlinx:kotlinx-io-core:0.6.0
org.jetbrains.kotlinx:kotlinx-io-bytestring:0.6.0

Third-party libraries

com.upokecenter:cbor:4.5.2
com.jakewharton.timber:timber:5.0.1

Android Permissions and Features

This SDK automatically adds a number of permissions and features to your Android Manifest. To control how these appear in your final APK you can use Android's manifest merger.

For example, to remove the internet permission, if you are not using OID4VCI in the Holder and do not need the internet permission otherwise, add the below to instruct the build tools to remove the internet permission node from the final merged manifest.

    <uses-permission tools:node="remove" android:name="android.permission.INTERNET" />

To inspect your final APK, you can use the AndroidSDK tool aapt, which can be found under the build-tools directory of your Android SDK install.

    $ aapt d badging path/to/your.apk

The Android documentation for this can be found here.

License & Compliance

Request or download the MATTR Pi SDK Trial License Agreement and the MATTR Customer Agreement and review these terms carefully.
Sign and return the MATTR SDK Trial License Agreement to us.

SDK Change Log

3.0.0 (26 May 2025)

Breaking changes

Spelling standardization change (UK → US English)

The following changes reflect the update of the SDK's spelling convention from UK English to US English:

Renamed the initialise function to initialize.
Renamed the deinitialise function to deinitialize.
The following exceptions under VerifierException namespace have been renamed:

SdkNotInitialisedException -> SdkNotInitializedException.
StorageInitialisationException -> StorageInitializationException.

Proximity presentation sessions management enhancements

To simplify proximity presentation state handling, we moved the proximity presentation interface to MobileCredentialVerifier. This implies the following changes:

The ProximityPresentationSession class was removed.
The MobileCredentialVerifier.getCurrentProximityPresentationSession function was removed.
The MobileCredentialVerifier.createProximityPresentationSession function:

Shares the session creation result (success or failure) via the callback.
Does not suspend anymore. It returns effectively immediately and establishes the session asynchronously.

The ProximityPresentationSession.requestMobileCredentials function was replaced by MobileCredentialVerifier.sendProximityPresentationRequest.
The ProximityPresentationSession.terminateSession function was replaced by MobileCredentialVerifier.terminateProximityPresentationSession.

MobileCredentialVerifier's implementation of Singleton pattern was simplified:

It is now a Kotlin object.
The MobileCredentialVerifier.getInstance function was removed.
The object's methods can now be accessed directly.

The presentation session's lifecycle can be observed via the ProximityPresentationSessionListener interface.

New features

NFC device engagement is now supported (only when interacting with Android holder devices). The following APIs were added:

MobileCredentialVerifier.registerForNfcDeviceEngagement.
MobileCredentialVerifier.deregisterForNfcDeviceEngagement

Added a MobileCredentialVerifier.deinitialize API.

Bug fixes

Fixed an issue where proximity presentation sessions would not terminate when Bluetooth was disabled.

Sample App

Support for NFC Engagement.
Improved UI.

2.0.0

Breaking changes

Removed statusInfo from MobileCredentialPresentation, MobileCredential and MobileCredentialMetadata.
Removed deviceKeyId from MobileCredential and MobileCredentialMetadata.

Features

The getTrustedIssuerCertificates function now computes the TrustedCertificate.verificationResult as well.
Improved performance of addTrustedIssuerCertificates when adding certificates with revocation lists.

Sample apps

The sample app now supports product flavours for different SDK types.
Fixed minor bugs.

1.1.0

This release compared to 1.0.1 includes:

Features

Feature to have two SDKs in one app.

Bug fixes

Fix Verifier SDK to populate verified status correctly.
Fix return values for updateTrustedIssuerStatusLists.
Fix logger configuration.
Improved cryptography for older devices.
Improved BLE hardware handling.
Improved read performance from local storage.

1.0.4 (Internal)

Bug fixes

Fix Verifier SDK to populate verified status correctly.

1.0.3 (Internal)

Features

Feature to have two SDKs in one app.

Bug fixes

Fix return values for updateTrustedIssuerStatusLists.
Fix logger configuration.
Improved cryptography for older devices.
Improved BLE hardware handling.
Improved read performance from local storage.

1.0.1 (Public release)

Breaking changes

All functions may now throw standard Errors that were previously masked.
All non-public methods and classes are now marked as internal or private.
The global.mattr.mobilecredentialverifier package was renamed to global.mattr.mobilecredential.verifier.
The DataTransportException exception was renamed to DataTransportDisconnectedException.

Features

The SDK now supports checking the revocation and suspension status of presented mDocs:

The requestMobileCredentials function now takes an skipStatusCheck boolean flag that will skip the status check when set to true. Defaults to false.

Operations now throw an UnsupportedCurveException exception when encountering an unsupported cryptographic curve.
Storage engine replacement, resulting in the removal the Realm dependency.
HTTP Client replacement to support Android 7, resulting in the removal of the OkHttp dependency.
Increased debug logging throughout SDK.
Updated all 3rd party libraries to recent versions.