Below are the guidelines and specifications for integrating any software development kit (SDK) with Inji Wallet:

1. The SDK should be implemented as a npm module that supports the React Native framework.

   For example, the npm modules, tuvali and secure-keystore, demonstrate suitable implementations.

2. The SDK should provide simple APIs for integration purposes.

   These APIs should include an API for instantiation or initialization, such as the init or constructor API.

3. The SDK should also include additional APIs that perform the necessary actions.

4. There should be an API available to disconnect the SDK, if needed.

   If possible, it would be beneficial for these APIs to be asynchronous. This enables users to continue using the application without experiencing any UI blocking.

5. To enhance logging and traceability, the API may accept an optional parameter known as traceabilityId.

By adhering to these specifications, the integrated SDK will enhance the functionality and usability of the application.

This section contains various guides and information that could benefit the developers, system integrators, relying parties and end users.

For more information on how to get started with integrations, read through:

1. Tuvali - Sharing via BLE

2. Face Match

3. Secure Keystore

4. BLE Verifier

5. PixelPass

6. Telemetry (details coming up soon)

Tuvali module is based on the OpenID for Verifiable Presentations over BLE implementation to support sending vc/vp using Bluetooth Low Energy local channel. The below sections explains the APIs of the library in detail.

Firstly, for establishing the secured connection over BLE the connection params which include name and key needs to be exchanged between the two devices. This exchange of parameters can be accomplished but is not limited to by using a QR code.

For example, use a QR code generator to visually display params and a QR code scanner to get params. A mobile app that displays a QR code can act as an Verifier by including its connection params as data in the QR code and another device can act as Wallet which scans the QR code, it can extract the connection parameters and initiate a BLE connection with the advertising device.

URI Exchange and Establishing Connection

Verifier

The Verifier device generates a URI using the startAdvertisement() method and displays it as a QR code. Once the advertisement starts, the Verifier continuously advertises with a payload derived from the URI.

URI contains:

OPENID4VP://connect?name=STADONENTRY&key=8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a

URI structure can be found in the spec. Currently the library doesnot support iOS as a verifier.But it can act as a wallet for android verifier.

var verifier = Verifier()
var uri = verifier.startAdvertisement()
println(uri)

Wallet

Start Connection

The device that scans the QR code will extract the connection parameters from the QR code and set its connection parameters using the startConnection() method :

var wallet = Wallet()
wallet.startConnection(uri)

The connection param is a URI with a name & a key. The name is the client's name & the key is the verfier's public key.

OPENID4VP://connect:?name=OVPMOSIP&key=69dc92a2cc91f02258aa8094d6e2b62877f5b6498924fbaedaaa46af30abb364

• The key part of the data is the same data that will be advertised by the verifier device but in hex-encoded form.

E.g: OVPMOSIP://connect:?name=<>&key=<verifier public key>

Share data

Once the connection is established, wallet app can send the data in a secured way to the Verifier. Note: At this moment, we currently support data transfer from Wallet to Verifier only.

wallet.sendData(payload);

and verifier app can acknowledge it.

verifier.sendVerificationStatus(status);

The following sequence of actions should be performed to transfer data over BLE:

1. Verifier must start advertising by calling verifier.startAdvertisement(name) method

2. Subscribe to events using wallet.handleDataEvents

3. Initiate the secure connection using wallet.startConnection(uri). The Wallet public keys are exchanged with verifier on successful connection.

4. Wallet calls wallet.sendData(payload) to transfer requisite data over BLE.

5. Send VC response - Verifier can exchange "Accept/Reject" status to Wallet with the following message type for verifier.sendVerificationStatus method

Subscribe to events

Data received from other apps via BLE can be subscribed to using: Tuvali sends multiple events to propagate connection status, received data etc. These events can be subscribed to by calling:

on Wallet:

wallet.subscribe {
  event  ->
  // Add the code that needs to run once event is received
}

on Verifier:

verifier.subscribe {
  event  ->
  // Add the code that needs to run once data is received
}

Here are the different types of events that can be received

Common Events

Events which are emitted by both Wallet and Verifier

1. ConnectedEvent

   • on BLE connection getting established between Wallet and Verifier

2. SecureChannelEstablishedEvent

   • on completion of key exchange between Wallet and Verifier

3. ErrorEvent

   • on any error in Wallet or Verifier

4. DisconnectedEvent

   • on BLE disconnection between Wallet and Verifier

Wallet Specific Events

1. DataSentEvent

   • on completion of Data transfer from the Wallet Side

2. VerificationStatusReceivedEvent

   • on received verification status from Verifier

Verifier Specific Events

1. DataReceivedEvent

• on receiving data from the Wallet Side

Connection closure

The device on which app is running can destroy the connection by calling disconnect() method:

wallet.disconnect();
verifier.disconnect();

Tuvali & Inji Integration

The below diagram explains the series of handshakes between the Verifier and the Wallet device.

PixelPass

PixelPass is a versatile and easy-to-use library designed to simplify working with QR codes and data compression. It allows you to generate QR codes from any given data with just a single function. If you’re working with JSON, PixelPass can take that data, compress it, and convert it into a compact format using CBOR encoding, making it smaller and more efficient for QR code generation. The library can also decode this compressed data, turning CBOR back into the original JSON format. Additionally, for more complex use cases, PixelPass offers the ability to map your JSON data to a specific structure, compress it, and encode it into CBOR. Later, you can also reverse this process, decoding the CBOR back into its mapped JSON structure. With these capabilities, PixelPass makes managing, compressing, and encoding data for QR codes easy and efficient.

PixelPass has NPM, Kotlin, Swift and Java artifacts available.

Features

• Compresses data using zlib with the highest compression level (level 9).

• Encodes and decodes data with the base45 format.

• For JSON data, applies CBOR encoding/decoding to achieve additional size reduction.

• With JSON and a Mapper provided, maps the JSON and then performs CBOR encoding/decoding to further shrink the data size.

Usage

1. As a node project:

npm i @mosip/pixelpass

1. As a Kotlin/Java dependency:

Gradle

implementation("io.mosip:pixelpass:0.5.0")

Maven

1. To include PixelPass in your Swift project, follow the below steps:

   1. Clone the PixelPass library locally.

   2. Create a new Swift project.

   3. Add package dependency: PixelPass

APIs

Below are the APIs provided by the PixelPass library:

generateQRCode( data, ecc , header )

The generateQRCode takes a data, ECC (Error correction level) which when not passed defaults to L and header which defaults to empty string if not passed. Returns a base64 encoded PNG image.

• data - Data needs to be compressed and encoded.

• ecc - Error Correction Level for the QR generated. defaults to "L".

• header - Data header need to be prepend to identify the encoded data. defaults to "".

generateQRData( data, header )

The generateQRData takes a valid JSON string and a header which when not passed defaults to an empty string. This API will return a base45 encoded string which is Compressed > CBOR Encoded > Base45 Encoded.

• data - Data needs to be compressed and encoded.

• header - Data header need to be prepend to identify the encoded data. defaults to "".

decode( data )

The decode will take a string as parameter and gives us decoded JSON string which is Base45 Decoded > CBOR Decoded > Decompressed.

• data - Data needs to be decoded and decompressed without header.

decodeBinary( data )

The decodeBinary will take a UInt8ByteArray as parameter and gives us unzipped string. Currently only zip binary data is only supported.

• data - Data needs to be decoded and decompressed without header.

getMappedData( jsonData, mapper, cborEnable )

The getMappedData takes 3 arguments a JSON and a map with which we will be creating a new map with keys and values mapped based on the mapper. The third parameter is an optional value to enable or disable CBOR encoding on the mapped data.

• jsonData - A JSON data.

• mapper - A Map which is used to map with the JSON.

• cborEnable - A Boolean which is used to enable or disable CBOR encoding on mapped data. Defaults to false if not provided.

The example of a converted map would look like, { "1": "207", "2": "Jhon", "3": "Honay"}

decodeMappedData( data, mapper )

The decodeMappedData takes 2 arguments a string which is CBOR Encoded or a mapped JSON and a map with which we will be creating a JSON by mapping the keys and values. If the data provided is CBOR encoded string the API will do a CBOR decode first ad then proceed with re-mapping the data.

• data - A CBOREncoded string or a mapped JSON.

• mapper - A Map which is used to map with the JSON.

The example of the returned JSON would look like, {"name": "Jhon", "id": "207", "l_name": "Honay"}

Errors / Exceptions

Shall you encounter any errors while using the APIs, please refer to the below:

1. Cannot read properties of null (reading 'length') - This error denotes that the string passed to encode is null.

2. Cannot read properties of undefined (reading 'length') - This error denotes that the string passed to encode is undefined.

3. byteArrayArg is null or undefined. - This error denotes that the string passed to encode is null or undefined.

4. utf8StringArg is null or undefined. - This error denotes that the string passed to decode is null or undefined.

5. utf8StringArg has incorrect length. - This error denotes that the string passed to decode is of invalid length.

6. Invalid character at position X. - This error denotes that the string passed to decode is invalid with an unknown character then base45 character set. Also denotes the invalid character position.

7. incorrect data check - This error denotes that the string passed to decode is invalid.

PixelPass & Inji Wallet Integration:

The below diagram shows how Inji Wallet utilises PixelPass library.

PixelPass & Inji Verify Integration:

The below diagram shows how Inji Verify utilises PixelPass library.

Face Match is an optional component in Inji Wallet. This is built as a standard that allows anyone to integrate their Facematch SDK. Its expected that the wallet providers would integrate the SDK that matches the specification.

The current specification is in draft state.

Contribution

We extend our sincere appreciation to the IRIScan team for their invaluable support to MOSIP by providing an opensource face match SDK for our internal reference integration. We are truly impressed by your commitment and outstanding contribution. We welcome and invite our other esteemed partners to collaborate with MOSIP, for a similar integration.

Repository

NPM Package

Installation

• To install any face sdk module, please add it's dependency in the package.json file.

• Once done rebuild the Inji Wallet.

• The Inji Wallet should be able to integrate and use the face sdk.

Face Compare with liveness is coming soon

• This feature enables Inji Wallet to verify specific parameters for liveness. We utilize local face verification to guarantee the user's presence during a transaction. This measure is implemented to combat fraud, going beyond the ISO/IEC 30101 standard.

• The following guidelines apply to individuals who are developing the face SDK:

  1. It is prohibited to collect any personally identifiable information (PII) or phone details.

  2. Inji Wallet includes built-in telemetry, and all telemetry data must be transmitted to the designated system. Telemetry enhances Inji Wallet's observability features by capturing specific events, creating measures, and monitoring various user actions and events.

  3. Recording or transmitting IP addresses, user details, Phone IMEI, phone numbers, or user photos in telemetry or logs is strictly prohibited.

  4. The use of phone numbers and device fingerprints should be limited to managing the SDK license.

VCI-Client

vci-client library enables to carry out the credential request from the consumer application (mobile wallet or web) and download the VC.

Features:

• Creates a credential request with access token, issuer metadata, holder jwt proof.

• Provide credential response (VC) to the consumer application.

• Kotlin and Swift artefacts are available to integrate with the native mobile applications.

Below sections details on the steps for integrating the Kotlin and Swift packages into the app.

Android: Kotlin package for vci-client:

Repository

• inji-vci-client repo is

• • Maven snapshots available

Installation

APIs

1. Request Credential

Request for credential from the providers (credential issuer), and receive the credential.

Parameters

Exceptions

• DownloadFailedException is thrown when the credential issuer did not respond with credential response

• NetworkRequestTimeoutException is thrown when the request is timedout

More details

An example app is added under /example folder which can be referenced for more details.

iOS: Swift package for vci-client:

Repository

Installation

1. Clone the repo

2. In your swift application go to file > add package dependency > add thehttps://github.com/mosip/inji-vci-client-ios-swift in git search bar> add package

3. Import the library and use.

APIs

1. Request Credential

Request for credential from the issuer, and receive the credential response back in string.

Parameters

Exceptions

• DownloadFailedError is thrown when the credential issuer did not respond with credential response

• NetworkRequestTimeOutError is thrown when the request is timedout

More details

An example app is added under /SwiftExample folder which can be referenced for more details. Extract the swift example app out of the library and then follow the installation steps.

VCI-Client and Inji Wallet integration:

The below diagram shows how Inji Wallet utilises vci-client library.

• This is the module built for verifiers to receive VC via BLE. This is a wrapper built on Tuvali with simplified APIs.

Repository

Installation

• Add a dependency in package.json

• Publishing npm module is WIP. Once it's published, it can be integrated as any other npm module.

API Specification

The following APIs are exposed to instantiate, start the transfer and stop the transfer

Constructor for initialization

• This API initializes the BLE module using the provided configuration. This initialization process allows for the sharing of configuration information for advertisement purposes. A new instance is created with each initialization.

• It is recommended to use one instance per session and to initialize a new instance for each subsequent session.

• The configuration passed to the constructor includes a parameter called deviceName. This name is included in the advertisement payload during the BLE advertisement. It is important to note that this field has a character limit of 11 characters.

Signature

Parameters

API to start transfer

• This API starts with advertisement for establishing the connection

• Internally interacts with Tuvali to start advertisement

• Update state to Advertising

• Once the secure connection is established, navigate through to state to complete the transfer

Signature

API to stop transfer

• This API has to be called explicitly to stop the connection

• Connection can be stopped either after successful transfer or user wants to cancel the transfer

• Once the connection is disconnected, state is updated to Idle

Signature

Types of states supported

• Idle

• Advertising

• Connected

• Secure Connection Established

• Requested

• Received

• Error

• Disconnected

Transitions between states is shown below:

Note: If either the sender or receiver decides to cancel the transfer at any stage, the state will transition to Disconnected and become Idle as a result.

Inji Wallet integration workflow with BLE Verifier SDK and Face Match SDK

Permissions

Android

Following permissions are required to be included in the AndroidManifest.xml to access Bluetooth Low Energy on Android.

Permissions required for Central (Wallet) when target is Android 12 or higher

Permissions required for Central (Wallet) when target is Android 11 or lower

Permissions required for Peripheral (Verifier) when target is Android 12 or higher

Permissions required for Peripheral (Verifier) when target is Android 11 or lower

iOS

Following permissions are required to be included in info.plist to access the Core Bluetooth APIs on iOS.

Minimum Version Requirements

BLE version: BLE 4.2 and above.

Android version: Android version 9 (API level 28) and above.

iOS version: The SDK requires iOS minimum deployment target version as 13.0.

Capabilities

• Wallet: In this role, Tuvali can discover Verifier devices over BLE and can connect and share data. This role is supported on both, Android and iOS devices meeting minimum version requirement.

• Verifier: In this role, Tuvali can advertise itself to Wallets and receive data. This role is supported only on Android devices at the moment. iOS doesn't support being a Verifier.

Secure Keystore

Secure Keystore is a library exclusively for Android platform. The devices which have a can use this library to perform encryption, decryption and computation of HMAC on the native side using the Hardware backed security features.

Artifacts

• Maven Snapshots are available

• NPM modules are available

Installation

The Secure Keystore is an independent module published as NPM module which provides Android APIs for the same on React. On a React Native application, this can be installed via

Usage

1. For RSA based Key Pair

1. For symmetric key

API documentation

deviceSupportsHardware

deviceSupportsHardware: boolean

Checks if the device supports hardware keystore.

generateKey

generateKey(alias: string) => void

Generates a symmetric key for encryption and decryption.

generateKeyPair

generateKey(alias: string) => string

Generates an asymmetric RSA key Pair for signing.

encryptData

encryptData(alias: string, data: string) => string

Encrypts the given data using the key that is assigned to the alias. Returns back encrypted data as a string.

decryptData

decryptData(alias: string, encryptionText: string) => string

Decrypts the given encryptionText using the key that is assigned to the alias. Returns back the data as a string.

sign

sign(alias: string, data: string) => string

Creates a signature for the given data using the key that is assigned to the alias. Returns back the signature as a string.

hasAlias

hasAlias(alias: string) => boolean

Checks if the given alias is present in the keystore.

This is the module that supports transferring verifiable credentials (VC) over Bluetooth Low Energy (BLE).

Let's have a look at how BLE communication works in general between the two devices A & B.

Repository:

• presents the kotlin library for tuvali

• to get details on swift artifact.

• contains the artefacts in maven.

Installation:

Usage as a Kotlin library (for native android)

1. In build.gradle.kts add the following:

The kotlin library has been added to your project.

Usage as a Swift library (for native ios)

1. Download swift artifact (ios-tuvali-library) from the repository.

2. Open your project in XCode.

3. Goto File > Add Package Dependencies.

4. Select Add Local option.

5. Add the artifact folder.

The swift library has been added to your project.

Before we understand how Tuvali works, let's go through BLE communication.

How does BLE Communication work?

In BLE communication, one device is designated as Peripheral and another one designated as Central.

Peripheral can perform advertisement which can be read by a Central device and connected to it, if the advertisement is connectable.

Once the connection is made, Central can perform further actions on the device like

• discovering services and characteristics

• subscribing to notifications on characteristics

• write/ read data from characteristics

• disconnect from device

While peripheral can perform actions like

• sending notifications to subscribed characteristics

• respond to read requests from Central

The above diagram explains the sequence of actions for BLE communication in general.

1. Advertisement from Peripheral

2. Connection establishment & additional data exchange

3. Service & Characteristic discovery from Central

4. The characteristic subscription on Peripheral

5. Write with response to characteristic

6. Write without response to the characteristic

7. Send Notification from GATT Server

8. Disconnection from GATT Server/ Client

More details about other BLE terminology used here can be found in standard BLE specifications of 4.2 and above.

How Tuvali works with BLE to transfer VC from Central to Peripheral

Note: Tuvali is supposed to implement OpenID for VP over BLE specification. As part of it, both VP request and response transfer should be implemented. However the current version of Tuvali only transfers VC from Central to Peripheral.

In the case of Tuvali, the entire VC transfer flow can be divided into the following stages

1. Connection Setup & Cryptographic key exchange

2. Data transfer

3. Connection Closure

1. Connection Setup & Cryptographic key exchange

Steps 1 to 6 mentioned in the above diagram explain how the first stage is achieved. Before even the advertisement is started, the peripheral generates a 32-byte public key. This public key is sent to Central in two parts. The first part will have 5 bytes of the public key sent as part of the advertisement payload and while the second part is sent as part of SCAN_RESP.

Since the advertisement from Peripheral is of connectable type, Central would send out a SCAN_REQ on receiving the advertisement and gets the remaining 27 bytes of the peripheral public key. Post that, Central would derive a public key pair and send its 32 bytes public key on Identify characteristic of Peripheral.

Once the public keys are exchanged between Central and Peripheral, a set of keys are derived on both sides which would be used for encryption and decryption of data on the wire.

Cryptographic Algorithm usage:

• Ephemeral Key Pair is generated from X25519 curve

• Key Agreement uses ECKA-DH (Elliptic Curve Key Agreement Algorithm – Diffie-Hellman) as defined in BSI TR-03111

• Wallet and Verifier derives respective keys using HKDF as defined in RFC5869

• Encryption/Decryption uses AES-256-GCM (192) (GCM: Galois Counter Mode) as defined in NIST SP 800-38D

2. Data transfer

Steps 7 to 11 mentioned in the above diagram explain how the second stage is achieved. Before VC is transferred, Central performs encryption and compression and communicates the resultant data size by writing to Response Size characteristic to Peripheral. The actual data transfer would happen on Submit Response characteristic.

Since the maximum allowed write value for a characteristic is limited to 512 bytes. The actual VC data is split by a component called Chunker into multiple smaller chunks. After the split, the data is transferred on the Submit responsecharacteristics one after another until all chunks are completely sent.

Peripheral on the other hand, receives data on the Submit response characteristic. The received chunks are collected and the final VC is assembled by a component called Assembler.

At the end of sending one frame of data from Central. It would request a transfer report via Transfer report request characteristic. Peripheral response with a summary of missing/corrupted chunks sequence numbers via another Transfer report summary characteristic.

Central would read the Transfer report summary to understand if the Peripheral received all the chunks properly. If the summary report has at least one chunk sequence number. Central would send those specific chunks to the Peripheral which is called the Failure frame.

The failure frame will be sent from Central repeatedly until the Transfer report summary is successful. If during the process, Central reached the maximum allowed failure frame retry limit, the transfer is halted, devices will be disconnected and an error is generated (Please refer to API documentation on how this error can be read).

• Gzip is the Compression algorithm used with default compression level

• Each chunk have 2 bytes of CRC-16/Kermit added. Parameters for the same are: width=16 poly=0x1021 init=0x0000 refin=true refout=true xorout=0x0000 check=0x2189 residue=0x0000 name="CRC-16/KERMIT"

3. Connection closure

Disconnect initiated by Peripheral:

• On a successful data transfer

• On non-recoverable error occurred on Peripheral

Peripheral notify Central to perform disconnection via Disconnect characteristic mentioned in Step 12 of the above diagram.

Disconnect initiated by Central

Central also performs disconnect in the following scenarios:

• On a successful data transfer

• Non-recoverable error on Central

• Peripheral is out of range/ disconnected

• Destroy Connection API

As part of connection closure, both central and peripheral clean the held resources, cryptographic keys, and Bluetooth resources, to ensure that the subsequent transfer happens smoothly.

Note: All the cryptographic keys generated/ derived are used only for a single VC transfer session. The library strictly ensures they are not re-used in subsequent VC transfers post connection closure.

Error Codes And Error Scenarios:

Error Code Format: <Component(2 Character)Role(1 Character)>-<Stage(3 Character)>-<Number(3 Character)>

Current Supported Stages: CON(Connection) | KEX(Key Exchange) | ENC(Encryption) | TRA(Transfer) | REP(Report) | DEC(Decryption) | UNK (Stage is unknown) Current Component+ Role Combinations: TVW(Tuvali+Wallet) | TVV(Tuvali+Verifier) | TUV(Tuvali where role is unknown)

List of Supported Error Codes:

• UnknownException: TUV_UNK_001

• WalletUnknownException: TVW_UNK_001

• CentralStateHandlerException: TVW_UNK_002

• WalletTransferHandlerException: TVW_UNK_003

• VerifierUnknownException: TVV_UNK_001

• PeripheralStateHandlerException: TVV_UNK_002

• VerifierTransferHandlerException: TVV_UNK_003

• InvalidURIException: TVW_CON_001

• MTUNegotiationException: TVW_CON_002

• ServiceNotFoundException: TVW_CON_003

• TransferFailedException: TVW_REP_001

• UnsupportedMTUSizeException: TVV_CON_001

• CorruptedChunkReceivedException: TVV_TRA_001

• TooManyFailureChunksException: TVV_TRA_002

Error Scenario 1: The verifier receives a Failed to transfer message and wallet receive a Disconnected message on the screen.

Possible error scenarios:

• During VC transfer, if there is a failure in the transfer of more than 70% of the data we get an exception on the verifier side and it disconnects from the wallet.

• After the verifier and wallet establish a connection, the wallet initiates an MTU negotiation with the verifier. If the negotiated MTU is less than 64 Bytes, then the verifier throws an exception and disconnects from the wallet.

• If the verifier receives the size of the VC as 0, it raises an exception and disconnects from the wallet.

Error Scenario 2: The wallet receives a Failed to transfer message and the verifier receives a Disconnected message on the screen.

Possible error scenarios:

• After the verifier and wallet establish a connection, the wallet initiates an MTU negotiation with the verifier. If the wallet is unable to negotiate the MTU with the verifier, it raises an exception and disconnects from the verifier.

• During VC transfer, if the transfer cannot be completed within the specified limit of retries, the wallet raises an exception and disconnects from the verifier.

• After the wallet sends all the chunks, it requests a transfer report. If the wallet is not able to send the request, it raises an exception and disconnects from the verifier.

Below are the exception message and the disconnect message which appears on the screen during the error.

This message is displayed on the device throwing the exception.

This message is displayed whenever a device gets disconnected.

Retry scenarios

• Backoff Strategy: Exponential Backoff is a technique that retries a failing operation, with an exponentially increasing wait time, up to a maximum retry count(MAX_RETRY_LIMIT) or maximum backoff time(MAX_ELAPSE_TIME).

  Initially, it starts with 2 ms as wait time (INITIAL_WAIT_TIME) and increases exponentially with each failure until the count reaches MAX_EXPONENT after which the wait time becomes constant (INITIAL_WAIT_TIME ^ MAX_EXPONENT).

  • BLE Service Discovery: After the connection is established, the central attempts to discover all the services hosted by the peripheral. If it fails to discover our service, then the exponential backoff-based retry will kick in. Here are the values:

    • MAX_RETRY_LIMIT is 5 for Android and 10 for IOS

    • MAX_ELAPSE_TIME is 100 ms

    • MAX_EXPONENT is 5

  • Request Transfer Report [only for iOS]: After the wallet writes all the chunks to the verifier, it requests the transfer report. If the transfer report request write fails, then the exponential backoff-based retry will kick in. Here are the values:

    • MAX_RETRY_LIMIT is 5

    • MAX_ELAPSE_TIME is 100 ms

    • MAX_EXPONENT is 5

• Dynamic MTU negotiation:

  • Android: After the connection is established, the wallet initiates an MTU negotiation with an initial value of 512 bytes. If it fails, it retries with 185 and 100 bytes subsequently with a wait time of 500 ms each. If the negotiation fails after all retries, it throws an exception and disconnects from the wallet.

  • iOS: iOS kicks off an MTU exchange automatically upon connection

Constants

• MAX_ALLOWED_DATA_LEN (509 Bytes): Maximum data length allowed for one write for both wallet and verifier.

• MIN_MTU_REQUIRED (64 Bytes): Minimum number of bytes required to share public key transfer of the wallet is 46. In order not to operate in edges, we chose the nearest value in the power of 2 i.e., 64.

• MAX_FAILURE_FRAME_RETRY_LIMIT (15): Maximum limit to retry sending failure chunks to the verifier.

Characteristics UUID

• IDENTIFY_REQUEST_CHAR_UUID (00000006-5026-444A-9E0E-D6F2450F3A77): Characteristic for sending the public key of the wallet.

• REQUEST_SIZE_CHAR_UUID (00000004-5026-444A-9E0E-D6F2450F3A77): Characteristic for requesting VC size by wallet from verifier.

• REQUEST_CHAR_UUID (00000005-5026-444A-9E0E-D6F2450F3A77): Characteristic for requesting the VC by the verifier.

• RESPONSE_SIZE_CHAR_UUID (00000007-5026-444A-9E0E-D6F2450F3A77): Characteristic for sending VC size to the verifier.

• SUBMIT_RESPONSE_CHAR_UUID (00000008-5026-444A-9E0E-D6F2450F3A77): Characteristic for sending the entire VC.

• TRANSFER_REPORT_REQUEST_CHAR_UUID (00000009-5026-444A-9E0E-D6F2450F3A77): Characteristic for requesting for transfer report from the verifier.

• TRANSFER_REPORT_RESPONSE_CHAR_UUID (0000000A-5026-444A-9E0E-D6F2450F3A77): Characteristic for sending transfer report to the wallet

• VERIFICATION_STATUS_CHAR_UUID (00002037-0000-1000-8000-00805f9b34fb): Characteristic for informing the wallet if the VC is accepted or rejected.

• DISCONNECT_CHAR_UUID (0000000B-5026-444A-9E0E-D6F2450F3A77): Characteristic for notifying the wallet to initiate the disconnection between the devices.

Service UUID

• SERVICE_UUID (00000001-0000-1000-8000-00805f9b34fb): Service UUID of the verifier

• SCAN_RESPONSE_SERVICE_UUID (00000002-0000-1000-8000-00805f9b34fb): Service UUID for uniquely identifying the scan response data to the wallet's SCAN_REQ

This telemetry module is derived from the sunbird telemetry module. It is responsible for generating events that can provide valuable analytics.

Note: The publication of this project is currently a work in progress and has not been released yet. Stay tuned for further announcements.