Biometric plugin

Purpose

The biometrics plugin provides a way to perform credential verification using the user's biometric data. It is useful to guarantee that only the biometric holder can perform the verification.

Flow

The biometric plugin flow is the following:

sequenceDiagram
    autonumber
    participant User
    participant BiometricPlugin as Biometric Plugin
    participant MobileWallet as Mobile Wallet
    participant WalletAPI as Wallet API

    User ->> MobileWallet: Scan QR code
    note over User, MobileWallet: Poof Request from Truvera 
    activate MobileWallet
    MobileWallet ->> BiometricPlugin: Initialize Biometric Plugin
    deactivate MobileWallet
    activate BiometricPlugin
    BiometricPlugin ->> MobileWallet: Check for existing EnrollmentCredential VC
    
    alt Enrollment VC not found
        BiometricPlugin ->> MobileWallet: Fetch Wallet DID
        BiometricPlugin ->> BiometricPlugin: Perform Biometric Check
        BiometricPlugin -->> WalletAPI: Issue EnrollmentCredential VC
        BiometricPlugin -->> WalletAPI: Issue BiometricMatchCredential VC
        BiometricPlugin ->> MobileWallet: Store EnrollmentCredential VC
        BiometricPlugin ->> MobileWallet: Store BiometricMatchCredential VC
       
    else Enrollment VC exists
        BiometricPlugin ->> MobileWallet: Fetch Wallet DID
        BiometricPlugin ->> BiometricPlugin: Perform Biometric Check
        BiometricPlugin ->> MobileWallet: Fetch existing BiometricMatchCredential VC
        BiometricPlugin -->> WalletAPI: Issue BiometricMatchCredential VC
        BiometricPlugin ->> MobileWallet: Store BiometricMatchCredential VC
    end
    deactivate BiometricPlugin
    activate MobileWallet
    MobileWallet ->> MobileWallet: Redirect user to the verification flow
    MobileWallet ->> MobileWallet: User selects the biometric check credential
    MobileWallet ->> TruveraAPI: Verify BiometricMatchCredential VC
    TruveraAPI ->> MobileWallet: Return verification result
    deactivate MobileWallet

How to trigger a biometric verification

To trigger a biometric verification, you need to use a verification template that asks for the biometric attributes. Check the following example:

{
  "id": "Credential 1",
  "name": "Forsur Verification - Biometrics Enrollment",
  "purpose": "Forsur wants to verify the ownership of - Biometrics Enrollment and the validity of the Biometrics Credentials.",
  "constraints": {
    "fields": [
      {
        "path": ["$.credentialSubject.id"]
      },
      {
        "path": ["$.credentialSubject.biometric.id"]
      },
      {
        "path": ["$.credentialSubject.biometric.created"]
      },
      {
        "path": [
          "$.issuer.id",
          "$.issuer",
          "$.vc.issuer.id",
          "$.vc.issuer",
          "$.iss"
        ],
        "filter": {
          "const": "did:dock:5HLbQLSmirNuZVRsdWKbsgdajw9QTGzSFJABSVzMT5EBj5sb"
        },
        "predicate": "required"
      }
    ]
  }
}

The presence of the following fields should trigger the biometric check:

{
  "path": ["$.credentialSubject.biometric.id"]
},
{
  "path": ["$.credentialSubject.biometric.created"]
}

How to enable the biometric plugin in the wallet

To enable the biometric plugin in a white-label wallet, you need to edit the following file src/wallet-sdk-configs.ts and add your configuration:

import { BiometricsProviderConfigs, IDVProviderFactory, setConfigs } from '@docknetwork/wallet-sdk-core/src/biometric-provider';
import { createTruveraIDVProvider, TruveraIDVConfig } from '@docknetwork/wallet-sdk-react-native/lib/truvera-biometric-plugin';
import { IWallet } from '@docknetwork/wallet-sdk-core/src/types';
import { EventEmitter } from 'events';

export const biometricProviderConfigs: BiometricsProviderConfigs<TruveraIDVConfig> = {
  enrollmentCredentialType: 'ForSurBiometricEnrollment',
  biometricMatchCredentialType: 'ForSurBiometric',
  idvConfigs: {
    ecosystemID: '<Ecosystem ID>',
    issuerDID: '<Issuer DID>',
    enrollmentCredentialSchema: '<Enrollment Credential Schema>',
    biometricMatchCredentialSchema: '<Biometric Match Credential Schema>',
    biometricMatchExpirationMinutes: 2,
    walletApiUrl: '<Wallet API URL>',
  },
};

setConfigs(biometricProviderConfigs);

export const idvProviderFactory: IDVProviderFactory = {
  create: (eventEmitter: EventEmitter, wallet: IWallet) => {
    return createTruveraIDVProvider({
      eventEmitter,
      wallet,
      configs: biometricProviderConfigs.idvConfigs,
    });
  },
};

The truvera biometric plugin requires the following configs:

• walletApiUrl: The URL of the wallet API that will be used to issue the credentials

• ecosystemID: The ecosystem ID of the biometric service

• issuerDID: The DID of the issuer

• enrollmentCredentialSchema: The schema of the enrollment credential

• biometricMatchCredentialSchema: The schema of the biometric match credential

• biometricMatchExpirationMinutes: The expiration time of the biometric match credential

Credential expiration

Credential expiration allows the biometric service provider to specify a maximum length to the validity of a biometric check credential. If the verifier wants to force a refresh of the biometric check more frequently, the verifier can check the credential creation timestamp during verification to ensure it's within their business rules.

Credential types

This plugin uses two types of credentials to perform the biometric verification:

• Enrollment Credential: This optional credential contains the biometric data of the user. The biometric data is stored in the credential subject field and will be used to perform the biometric match.

• Biometric Match Credential: This credential is issued by the biometric plugin after the biometric match. It contains the biometric ID, the issuer, and the creation date. The verifier can use this credential to check if the biometric match was performed recently and by the same issuer, and it will not contain any biometric data.

How to bind a biometric to a credential

Before issuing a credential, the issuer may request to verify the biometric check credential. If a valid credential does not exist, the wallet will trigger the biometric plugin to confirm the biometric and issue a credential.

The biometric check credential needs a unique binding ID that can only be generated by that specific user. The issuer can then include in the primary credential, the biometric ID and biometric issuer as attributes that bind that credential to that holder's biometric.

At the time of verification, the verifier can request the biometric check credential along with the primary credential. If the biometric check credential is recent enough, from the same issuer, and contains the same biometric ID, then the verifier can know it is the same holder presenting the credential.

The biometric ID should not contain the user's actual biometric information. When enrolling a holder in the biometric service, it might be useful to issue an enrolment credential containing the biometric template, the generated biometric ID and any other needed information to identify a returning user. This credential can be verified to get the user's information before checking their biometric. By storing this information with the holder, it avoids the biometric service having to store that PII outside of the control of the holder. The holder should only share a biometric enrollment credential with the biometric service that issued it.

TrustX Biometric Plugin

The TrustX biometric plugin uses the TrustX API to perform biometric verification and implements the IDVProvider interface.

import { BiometricsProviderConfigs, IDVProviderFactory, setConfigs } from '@docknetwork/wallet-sdk-core/src/biometric-provider';
import { createTrustXIDVProvider, TrustXIDVConfig } from '@docknetwork/wallet-sdk-react-native/lib/trustx-biometric-plugin';
import { DataStoreConfigs } from '@docknetwork/wallet-sdk-data-store/src/types';
import { DEFAULT_WALLET_CONFIGS } from '@docknetwork/wallet-sdk-react-native/lib/wallet';
import { IWallet } from '@docknetwork/wallet-sdk-core/src/types';
import { EventEmitter } from 'events';

export const biometricProviderConfigs: BiometricsProviderConfigs<TrustXIDVConfig> = {
  enrollmentCredentialType: 'ForSurBiometricEnrollment',
  biometricMatchCredentialType: 'ForSurBiometric',
  idvConfigs: {
    walletApiUrl: 'https://bank-demo.truvera.io/api',
  },
};

setConfigs(biometricProviderConfigs);

export const idvProviderFactory: IDVProviderFactory = {
  create: (eventEmitter: EventEmitter, wallet: IWallet) => {
    return createTrustXIDVProvider({
      eventEmitter,
      wallet,
      configs: biometricProviderConfigs.idvConfigs,
    });
  },
};

export const dataStoreConfigs: DataStoreConfigs = DEFAULT_WALLET_CONFIGS;

Adding a custom biometric provider

Adding a custom biometric provider will require the development of the plugin following the IDVProvider interface defined at packages/core/src/biometric-provider.ts. The plugin should implement the following methods:

• enroll: Enrolls the biometric data. It should issue an enrollment credential and a match credential.

• match: Performs the biometric match and if it is valid, returns a biometric match credential.

The plugin should be registered in the wallet-sdk-configs.ts file.