mobile-credential-verifier-react-native

Table of Contents

• Licensing
• Features
• Getting started
• Usage
  • Initialise
  • Trusted issuers
  • Request credentials
  • Error handling

Licensing

Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms

Features

• Manage trusted issuers
• Request mobile credentials

Getting started

How to get access to MATTR Pi Mobile Credentials Verifier SDK

Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.

Please reach out to us in case you need any assistance Get in touch.

Install dependencies

Add this SDK as a dependency to the react native app:

yarn add @mattrglobal/mobile-credential-verifier-react-native
Copy

Usage

Initialise

Initialise the SDK:

[!NOTE] SDK must be initialised first, otherwise other methods will throw an exception when invoked.

import { initialise } from "@mattrglobal/mobile-credential-verifier-react-native";

await initialise();
Copy

Trusted issuers

Manage trusted issuer certificates

import {
  addTrustedIssuerCertificates,
  getTrustedIssuerCertificates,
  deleteTrustedIssuerCertificate,
} from "@mattrglobal/mobile-credential-verifier-react-native";

// Add a new certificate
const addCertificateResult = await addTrustedIssuerCertificates([
  "MIIBwzCCAWmgAwIBAgILAOZSe5t+MOzXtX8wCgYIKoZIzj0EAwIwIDEeMAkGA1UEBhMCTlowEQYDVQQDEwpNQVRUUiBJQUNBMB4XDTIzMDcxODIwMDYzM1oXDTMzMDcxNTIwMDYzM1owIDEeMAkGA1UEBhMCTlowEQYDVQQDEwpNQVRUUiBJQUNBMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0XWwfvFPzbBHiDVLefOueGG1DMHc8WRfXfZqD6748kLZNTOBysm635yM7YCMlkUxDEIHVkLeyV6KoAOM2o0i5qOBiTCBhjASBgNVHRMBAf8ECDAGAQH/AgEDMA4GA1UdDwEB/wQEAwIABjAdBgNVHQ4EFgQUypKEavotsICoAsXypAUUlsVUylMwHAYDVR0SBBUwE4ERaW5mb0BtYXR0ci5nbG9iYWwwIwYDVR0fBBwwGjAYohaGFGh0dHBzOi8vbWF0dHIuZ2xvYmFsMAoGCCqGSM49BAMCA0gAMEUCIClmASfWcf/K2WbClaERQfA38TNTSgYZu2SdNeNFdQyGAiEAhfk+FloZkNOb6TOLcDGqSNwXf+NzvPX0yl+8aq+rMKQ=",
]);

if (addCertificateResult.isErr()) {
  const { error } = addCertificateResult;
  // handle error scenarios
  return;
}

// Get list of all stored certificates
const certificates = await getTrustedIssuerCertificates();

// Delete certificate by id
await deleteTrustedIssuerCertificate(certificateId);
Copy

Request credentials

Request Mobile Credentials:

import {
  createProximityPresentationSession,
  sendProximityPresentationRequest,
  terminateProximityPresentationSession,
} from "@mattrglobal/mobile-credential-verifier-react-native";

// Create new session
const createSessionResult = await createProximityPresentationSession({
  deviceEngagement: "mdoc:owBjMS4wAYIB2BhYS6QBAiABIVgg_t9K0BaXU27ynODS5q8OcvBZ4m1HFEQwl61lhRD2rdciWCA7hKLr_xN6_bdznDePa_yY1tGdHsc8ni_88uVuehRU-QKBgwIBowD1AfQKUMW8DfgLrUclmxp2InJCddk" // proximity presentation device engagement string
  onConnected: () => {
    // handle onConnect event
  },
  onSessionTerminated: () => {
    // handle onSessionTerminated event
  },
});

if (createSessionResult.isErr()) {
  const { error } = createSessionResult;
  // hande error scenarios
  return;
}

// Send session
const sendRequestResult = await sendProximityPresentationRequest({
  mobileCredentialRequests: [{
    docType: "org.iso.18013.5.1.mDL",
    namespaces: {
      "org.iso.18013.5.1": {
        family_name: false,
        driving_privileges: false,
      },
    },
  }],
});

if (sendRequestResult.isErr()) {
  const { error } = sendRequestResult;
  // handle error scenarios
  return;
}

const response = sendRequestResult.value;

// Terminate current active session
await terminateProximityPresentationSession();
Copy

Error handling

Functions that are expected to have an error path return a Neverthrow Result type that represents either success (Ok) or failure (Err).

Although this pattern is more verbose, it encourages the handling of possible errors and reserves throwing exceptions for truly exceptional situations.

import { sendProximityPresentationRequest } from "@mattrglobal/mobile-credential-verifier-react-native";

// Send session
const sendRequestResult = await sendProximityPresentationRequest(...);

if (sendRequestResult.isErr()) {
  const { error } = sendRequestResult;
  // handle error scenarios
  return;
}

const response = sendRequestResult.value;
Copy

unwrap

A utility function is provided for convenience if you decide not to handle your errors as results. This function will simply throw an error if the function passed in returns a Result where Result.isErr() is true.

import { unwrap, sendProximityPresentationRequest } from "@mattrglobal/mobile-credential-verifier-react-native";

try {
  const sendRequestResult = unwrap(await sendProximityPresentationRequest(...));
} catch (error) {
  // Handle thrown error
}
Copy

Change Log

3.0.0

BREAKING CHANGES

• The createProximityPresentationSession method could return the following errors:

  • MobileCredentialVerifierErrorType.BluetoothDisabled when Bluetooth is powered off.

• The sendProximityPresentationRequest method could return the following errors:

  • MobileCredentialVerifierErrorType.SessionTerminated when the current proximity presentation session is terminated.

• The onSessionTerminated callback function for createProximityPresentationSession method could be invoked with the following errors:

  • ProximityPresentationSessionTerminationError.ResponseNotReceived when mobile credential response not received from holder.

Features

• Allow additional extended key usage in a document signer certificate.
• Allow clock skew tolerance during verification.

Bug Fixes

• To mitigate a potential race condition issue, we have improved the process of generating new encryption keys.

iOS specific

• Fixed an issue where Bluetooth sessions might have been terminated before data exchange is completed. This can occur when the developer terminates the session after receiving a single response, but that response doesn't include all the required data. This might happen on devices with lower data transmission speed or when the response size is too big.

Android specific

• Fixed an issue where the SDK was unable to handle mobile credential presentation responses with floating point claims.

Notes

• The SDK now supports React Native 0.72.14.

2.0.0

BREAKING CHANGES

• Refined structure for credential errors in MobileCredentialResponse objects

Features

• Added support for Android platform

Bug Fixes

• Fixed error handler for createProximityPresentationSession and sendProximityPresentationRequest functions
• Fixed createProximityPresentationSession to unregister React Native event listeners on error

Notes

• Dependency upgrades and vulnerability fixes

1.0.1

Notes

• Enhance documentation

1.0.0

Features

• Add support for mobile credential (ISO Only). The current functionality includes

  • Manage mobile credential trusted issuer certificates
  • Request mobile credentials from a credential holder device