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 summarized 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) authorization 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). The SDK supports both the Authorization Code and Pre-Authorized Code flows.
Interface with a verifier and present an issued mDoc for verification/inspection:

In-person via Bluetooth as per ISO/IEC 18013-5:2021.
Remotely via internet connection as per ISO/IEC 18013-7:2024 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:

Feature	Options Supported	Default Option Selected
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:

Feature	Options Supported	Default Option Selected
Data Retrieval methods	OID4VP	OID4VP
Wallet Invocation	Custom URL and QR Code-based	Both
MDoc Reader validation	Stored verifier certificates, client Metadata retrieval	Both
Authorization 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. 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

Third-party libraries

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" />

Alternatively, if you're using the location permissions you will need to remove the maxApiLevel attribute.

    <uses-permission
        tools:remove="android:maxSdkVersion"
        android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission
        tools:remove="maxSdkVersion"
        android:name="android.permission.ACCESS_COARSE_LOCATION" />

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

5.1.0 (2025-10-10)

Features

OID4VCI manual redirect support

This enhancement allows applications to implement the OpenID4VCI issuance workflow within embedded WebViews while maintaining full control over the redirect flow.

Applications can now:

Call the new createAuthorizationSession(credentialOffer:clientId:) method to initiate the flow. This returns an AuthorizationSession object containing both the authorizeUrl and codeVerifier properties.
Load the returned authorizeUrl in a WebView to handle user authentication and consent.
After successful authentication, capture the redirect using the configured redirectUri, then extract the authorization code from the returned URL.
Complete the issuance workflow by calling the new retrieveCredentials(authorizationSession:authorizationCode:) method, passing in the AuthorizationSession and extracted authorization code.

Bug fixes

Fixed an issue where closing the embedded browser during the OpenID4VCI authorization flow caused retrieveCredentials to hang indefinitely.

5.0.0 (2025-09-30)

Breaking changes

JSON representation of VerifierAuthenticationResult now uses result instead of type for the authentication result type.

Bug Fixes

Fixed an issue where special characters in credential offers were escaped twice.
Fixed a bug where ResponseFailedException was thrown instead of UserAuthenticationBiometryLockoutException in the OnlinePresentationSession.sendResponse method. Fixed an issue where MobileCredentialHolder.addCredential could incorrectly throw a TrustedIssuerCertificateNotFoundException during unrelated trust chain evaluation failures.

Enhancements

Improved the performance of storage operations with large data sets.
Exposed the title and description of the authentication prompt as @string/global_mattr_unlock_storage_title and @string/global_mattr_unlock_storage_description. These values can be overridden in a resource file.
Documentation updates.

4.1.1 (2025-08-12)

Fixed an issue where special characters in credential offers were escaped twice.

4.1.0 (2025-07-29)

Features

mDoc Reader Authentication

The SDK no longer checks the signature algorithm when adding verifier certificates. This aligns with ISO/IEC 18013-5:2021, which does not specify required algorithms for reader root certificates.

Bug fixes

Resolved a potential crash when establishing a BLE connection.
Fixed an issue where the browser would retain focus after authenticating during credential retrieval via OpenID4VCI.
Fixed validation for ES384 and ES512 signatures.
Enabled using RSA as a digital signature algorithm for Reader Authentication root certificates.

4.0.0 (2025-07-07)

Breaking changes

Made deinitialize method idempotent.
Made deinitialize method non-throwing.

User authentication configuration

The initialize method now allows configuring how biometric authentication is performed. To allow this the following changes were introduced:

Introduced a new UserAuthenticationConfiguration class.
Introduced a new UserAuthenticationBehavior enum. Its value must be passed to the constructor of UserAuthenticationConfiguration to set up a desired authentication behavior.
Replaced the userAuthRequiredOnInitialize boolean parameter in initialize method with userAuthenticationConfiguration of type UserAuthenticationConfiguration.
Renamed HolderException.UserAuthenticationOnInitChangedException to HolderException.UserAuthenticationConfigurationChangedException.
Replaced HolderException.SdkInitializedWithDifferentInstanceIdException with HolderException.SdkInitializedException in initialize method. It is thrown if the SDK is initialized, independently of the instance ID.
HolderException.ActivityRequiredException is added to exception list of initialize, retrieveCredentials, and generateDeviceKey methods. Refer to enhancements section, and the methods' reference documentation for more details.
Replaced ProximityPresentationSession.MobileCredentialRequest with issuance.dto.MobileCredentialRequest.

Features

mDoc Reader Authentication

Added support for mDoc Reader authentication as defined in ISO/IEC 18013-5:2021. The SDK can now be used to inspect the verifier authentication result and enable the user to decide whether to share credentials with an unauthenticated verifier.

Introduced VerifierAuthenticationResult class which represents the mDoc Reader Authentication result.
Introduced verifierAuthenticationResult property of type VerifierAuthenticationResult? in MobileCredentialRequest.
Introduced a VerifierInfo class which represents information regarding the root certificate used to verify the request.
Introduced VerifierAuthenticationFailureType enum which represents an error which caused the mDoc Reader authentication to fail.

Enhancements

Introduced support for future dated credentials. The addCredential method can now be used to add credentials with a future validity period to the storage.
Added an msoHash property to the MobileCredential and MobileCredentialMetadata classes. The property represents a hashed mobile security object, defined in ISO/IEC 18013-5:2021. Note: This property is distinct from the id property and should not be used in the getCredential method.
initialize now accepts a Context instead of an Activity.

An Activity is still required for authentication if UserAuthenticationBehavior.OnInitialize is selected.
If an Activity is required but not provided, initialize will throw a HolderException.ActivityRequiredException.

activity parameter became optional in retrieveCredentials and generateDeviceKey methods.

An Activity is still required for authentication if UserAuthenticationBehavior.OnDeviceKeyAccess was selected during initialization.
If an Activity is required but not provided, the methods will throw a HolderException.ActivityRequiredException.

retrieveCredentials method now also throws HolderException.InvalidTransactionCodeException if the provided transaction code does not match the one expected by the issuer. Previously the exception was thrown only if the transaction code's format was wrong.

Sample App

Added a text field for reader authentication result in Proximity Presentation UI.
Added user authentication behavior selection in initialization screen.
Added MSO hash information to credential-related UI.
Minor UI improvements and bug fixes.

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 the HolderException namespace have been renamed:

SdkNotInitialisedException -> SdkNotInitializedException.
SdkInitialisedException -> SdkInitializedException.
AuthenticationCancelledException -> AuthenticationCanceledException.
SdkInitialisedWithDifferentInstanceIdException -> SdkInitializedWithDifferentInstanceIdException.
InvalidAuthorisationRequestUriException -> InvalidAuthorizationRequestUriException.
InvalidAuthorisationRequestVerifiedByDomainException -> InvalidAuthorizationRequestVerifiedByDomainException.
InvalidAuthorisationRequestVerifiedByCertificateException -> InvalidAuthorizationRequestVerifiedByCertificateException.
InvalidAuthorisationRequestUriException -> InvalidAuthorizationRequestUriException.
UserAuthenticationCancelledException -> UserAuthenticationCanceledException.
StorageInitialisationException -> StorageInitializationException.

OpenID4VCI Pre-authorized Code flow support

The SDK now supports claiming credentials via the OID4VCI Pre-Authorized Code flow,

Below is a summary of the technical changes introduced as part of this update:

retrieveCredentials function:

Now accepts a raw URL-encoded credential offer instead of a DiscoverCredentialOffer object. Thus, calling discoverCredentialOffer is now optional.
Does not accept redirectUri and autoTrustMobileCredentialIaca. These are now configured during SDK initialization.
Accepts transactionCode as an optional parameter. This is required when the Pre-Authorized Code flow includes a transaction code.

The initialize function now accepts a credentialIssuanceConfiguration parameter which
contains redirectUri and autoTrustMobileCredentialIaca (these were previously passed to the retrieveCredentials function).
DiscoveredCredentialOffer data class:

Removed authorizeEndpoint, tokenEndpoint, credentialEndpoint, and mdocIacasUri properties.
Added a transactionCode property to indicate whether or not a transaction code is required.

RetrieveCredentialResult data class: Renamed doctype to docType to align with other data classes in the SDK.
RetrieveCredentialError enum: Renamed name property to type in the JSON representation of the enum entities.

For more details, please refer to the corresponding methods and classes documentation.

Error handling consolidation

In order to provide a more cohesive and manageable error handling experience in the OID4VCI flow, we have consolidated several exceptions into broader ones. This change aims to make it easier for developers to handle errors consistently. Below is a summary of the changes:

discoverCredentialOffer() no longer throws the following exceptions:
- CredentialOfferNotFoundException
- InvalidCredentialOfferException
- CredentialOfferNotInCredentialIssuerMetadataException
- IssuerMetadataServiceException
- SupportedCredentialsNotFoundException
These have been consolidated into:

InvalidCredentialOfferException
FailedToDiscoverCredentialOfferException

retrieveCredentials() no longer throws the following exceptions:
- InvalidCredentialOfferException
- GenerateAuthorisationUrlFailedException
- AuthCodeNotFoundException
- AuthenticationFailedException
- TokenServiceException
- UnsupportedTokenTypeException
- DeviceKeyGenerationException
- UserAuthenticationOnDeviceNotSetupException
- AuthenticationCancelledException
- UserAuthenticationUnrecoverableKeyException
- UserAuthenticationBiometryLockoutException
- UserAuthenticationException
- IacaCertDownloadException
These have been consolidated into:
- InvalidCredentialOfferException
- FailedToRetrieveCredentialsException
- WebAuthenticationFailedException
- FailedToDiscoverCredentialOfferException
While the following exception types were added:

RedirectUriNotFoundException
InvalidTransactionCodeException

For a complete list of exceptions thrown by the discoverCredentialOffer() and retrieveCredentials() methods, refer to the methods' documentation.

Other breaking changes

ProximityPresentationSessionListener interface was moved from global.mattr.mobilecredential.common.session to global.mattr.mobilecredential.verifier.

Dependencies updates

Added org.jetbrains.kotlinx:kotlinx-io-core:0.6.0.
Added org.jetbrains.kotlinx:kotlinx-io-bytestring:0.6.0.
Updated com.upokecenter:cbor from 4.2.0 to 4.5.2.

Bug fixes

Fixed an issue where proximity presentation sessions would not terminate when Bluetooth was disabled.
Fixed an issue where large credentials were being cut off when sent with a terminating session status.
Fixed an issue which resulted in endless user authentication loop on some Samsung devices.

Sample App

Standardized spelling from UK to US English throughout the sample app codebase.
Added support for claiming a credential via the OID4VCI Pre-Authorized Code flow.

2.0.0

Breaking changes

Removed statusInfo from MobileCredentialPresentation, MobileCredential and MobileCredentialMetadata.
Removed the skipStatusCheck parameter from getCredentials.
Removed deviceKeyId from MobileCredential and MobileCredentialMetadata.
During an online presentation flow, the authorization request certificate must include the client_id as a subject alternative name record.

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 logger configuration.
Improved cryptography for older devices.
Improved BLE hardware handling.
Improved read performance from local storage.
Change HolderException.EmptyClientIdException from internal to public.

1.0.4 (Internal)

Bug fixes

Change HolderException.EmptyClientIdException from internal to public.

1.0.3 (Internal)

Features

Feature to have two SDKs in one app.

Bug fixes

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

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.