mDocs Holder SDK

Overview

The mDocs Holder SDK is based around the ISO/IEC 18013-5 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.

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

Generate, store and manage access to:

mDocs issued to an application integrating the SDK.
Device keys which are bound to issued mDocs.

Manage lists of:

Trusted issuer certificates which issued mDocs can be validated against.
Trusted verifier certificates which are used to validate OID4VP(OpenID for Verifiable Presentations) authorisation requests fetched as part of an mDoc retrieval flow.

Use referenced Status lists to to check mDocs' revocation status.
Interface with an issuer to obtain an mDoc as per OpenID4VCI (OpenID for Verifiable Credential Issuance).
Interface with a verifier and present an issued mDoc for verification/inspection:

In-person via Bluetooth as per ISO 18013-5.
Remotely via internet connection as per ISO/IEC 18013-7 and OID4VP.

In this SDK mDocs are referred to as Mobile Credentials.

Supported ISO/IEC 18013-5 Features

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


Device Engagement	QR Code-based	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

Supported ISO/IEC 18013-7 Features

The ISO/IEC 18013-7 technical specification contains many different features, some of which are not currently supported by this SDK. Below is a summary of supported features:


Data Retrieval methods	OID4VP	OID4VP
Wallet Invocation	Custom URL and QR Code-based	Both
MDoc Reader validation	Stored verifier certificates, client Metadata retrieval	Both
Authorisation Response Encryption	ECDH in Direct Key Agreement mode	ECDH in Direct Key Agreement mode

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.

SDK Change Log

1.0.1

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.mobilecredentialholder package was renamed to global.mattr.mobilecredential.holder.
discoverCredentialOffer function:

Throws a new ConnectivityException exception.
IssuerMetadataServiceErrorException was renamed to IssuerMetadataServiceException.

retrieveCredentials function:

Throws new ConnectivityException and IacaCertDownloadException exceptions.
TokenServiceErrorException was renamed to TokenServiceException.

createOnlinePresentationSession function:

Throws new ConnectivityException exception.
RequestServiceException and InvalidAuthorisationRequestException were removed.

DiscoveredCredentialOffer data class:

credentialsEndpoint was renamed to credentialEndpoint.

The getCredentials function now returns a list of MobileCredentialMetaData instead of MobileCredential.
The destroy function throws SdkInitialisedException instead of SdkNotInitialisedException.
The following exceptions were renamed:

UserAuthenticationCancelledException was renamed to AuthenticationCancelledException.
UserAuthenticationNotSetUpException was renamed to UserAuthenticationOnDeviceNotSetupException.
RequestNotReceivedException was renamed to MobileCredentialRequestNotReceivedException.
GenerateAuthorizationUrlFailedException was renamed to GenerateAuthorisationUrlFailedException.
DeviceKeyInUseException was renamed to DeviceKeyAlreadyInUseException.
DataTransportException was renamed to DataTransportFailedException.

Features

The SDK can now display and check credentials' revocation and suspension status:

The getCredentials function now takes an optional skipStatusCheck boolean flag that will skip the status check when set to true. Defaults to false.
The getCredential function now takes an optional 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.
Increased debug logging throughout SDK.
Updated to support Android 15.
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.
Updated all 3rd party libraries to recent versions.

Bug fixes

Occasional errors when using biometrics to unlock the KeyStore certain devices will now fallback to using PIN/password.

Sample app

Displays credentials' revocation and suspension status.
Allows copying of IACA PEM data.

0.6.1 (Tech preview release)

Breaking changes

Authentication on SDK initialisation MobileCredentialHolder.initialise() is now optional.
Authentication flow timeout changed from 1 to 3 seconds.

Features

Updated to support Android 14.

Sample app

Support for optional authentication.

0.6.0 (Internal release)

Features

Support for online mDocs presentation via OpenID4VP.

Sample app

Supports Online Presentation of mDocs via the OpenID4VP workflow.

0.5.4 (Initial Tech preview release)

Features

Support for claiming mDocs via the OpenID4VCI workflow.

Sample app

Supports claiming mDoca mDoc via the OpenID4VCI workflow.

Licence & Compliance

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