1 of 29

Supporting Components

Biometrics

Integrate and manage biometric components with MOSIP using standard interfaces, supported modalities, and compatibility guidelines.

Overview

MOSIP platform integrates with the following biometric key components:

Biometric devices - Captures biometric data (fingerprint, iris, and face) for registration and authentication.
ABIS - Facilitates biometric de-duplication and identification to ensure uniqueness and prevent identity fraud.
Biometric SDK - Provides integration tools for biometric data capture, processing, and quality checks.

All biometric components must comply with MOSIP's standard interfaces. Compatibility can be verified using the provided test kits.

Vendors supplying biometric systems are recognized as MOSIP Partners.

Modalities

MOSIP supports the following biometric modalities:

Fingerprint - Defines fingerprint capture and authentication device specifications per ISO 19794-4:2011, covering resolution, image quality, compression, and operational standards.
Iris - Outlines iris capture and authentication device specifications per ISO 19794-6:2011, detailing resolution, image quality, compression, and operational standards.
Face - Defines face capture and authentication device specifications per ISO 19794-5:2011, covering camera quality, image standards, compression, and operational requirements.

ABIS

Overview

Providing a unique identity for a resident is one of the key features of any identity platform. To achieve this, MOSIP interfaces with an Automated Biometric Identification System (ABIS) to perform the de-duplication of a resident's biometric data.

The ABIS system never learns about residents' identities. Any Personally Identifiable Information (PII), such as demographic details or an applicant's AID (application ID), is not shared with the ABIS system. Internally, MOSIP maintains a mapping between the ABIS-specific reference ID and the AID of the resident.

ABIS is used for 1:N deduplication. For 1:1 authentication, Biometric SDK is used. MOSIP does not recommend using an ABIS for 1:1 authentication.

MOSIP-ABIS interface

MOSIP interacts with ABIS only via message queues. The JSON format is used for all control messages in the queue. MOSIP ABIS middleware sends requests to the inbound queue address and receives responses from the outbound queue address. ABIS must comply with the interface defined in ABIS API Specifications

The interface may be tested using the ABIS testing kit.

ABIS must support the following types of biometric images:

Individual fingerprint images (segmented)
Iris images (left, right)
Face image

Biometrics data in MOSIP is exchanged as per formats defined in Biometric Image Specification.

Test kits

MOSIP provides kits to test the interface. Refer to the abis-testing-kit repo

ABIS deployment

ABIS must comply with ABIS API Specifications.
The queues can be configured in the RegistrationProcessorAbis-env.json file. The ABIS system connects to the queues using a pre-defined user ID and password.
It is recommended that ABIS be deployed in the same secure zone (military zone) where the registration processor is deployed.
ABIS system is not recommended to connect to any external network.

ABIS API

This document defines the APIs specifications for various operations that ABIS can perform to integrate with MOSIP.

API specification version: 0.9

Published Date: February 05, 2021

Revision Note

Publish Date

Revision

May 07, 2020

This is the first formal publication of the interface as a version-ed specification. Earlier draft are superseded by this document. The interface is revamped to make it friendlier to programmers and also has a new method for conversion.

June 09, 2020

A note related to targetFPIR was added.

June 26, 2020

August 04, 2020

November 19, 2020

Note on encryption of biometric data share using referenceURL has been added.

February 05, 2021

March 23, 2021

May 3, 2021

The logic for encryption has been updated for ABIS Datashare URL.

September 8, 2021

All possible error codes for DataShare URL has been added.

Introduction

An ABIS system that integrates with MOSIP should support the following operations.

Insert
Identify
Delete
Ping
Pending Jobs
Reference Count

All ABIS operations are via. a message queue and are asynchronous. The data sent in ABIS can be byte array or text based on a configuration in the registration processor.

Parameters

Common Parameters

Common parameters used for all ABIS operations:

Name

Description

Restrictions

Type

requestID

ID that is associated with each request sent to ABIS

ABIS should not use this ID in any other context outside the request

UUID

referenceID

ID of a single registration record. Registration record is maintained in MOSIP. This ID is the mapping between MOSIP and ABIS

None

UUID

referenceURL

URL to the biometrics data stored in MOSIP. This URL will have read only access

None

HTTPS URL

biometricType

Type of biometric data sent in the request

FID/FIR/IIR

String

returnValue

Code for response

String

failureReason

Code for failure reason

String

Standard Return Codes

Code

Status

Success

Failed

Failure Reasons

Code

Reason

internal error - Unknown

aborted

unexpected error

unable to serve the request - invalid request structure

missing referenceId (in request body)

missing requestId (in request body)

unable to fetch biometric details (using referenceURL)

missing reference URL (in request body)

missing requesttime (in request body)

referenceId already exists (in ABIS)

CBEFF has no data

referenceId not found (in ABIS)

invalid version

invalid id

invalid requesttime format

invalid CBEFF format

data share URL has expired

Biometric Quality check failed

ABIS Operations

The following operations are supported by MOSIP:

Insert
Identify
Delete
Ping
Pending Jobs
Reference Count

Insert

ABIS must get biometric data from referenceURL, process it and store it locally within the ABIS reference database. More details about the referenceURL is mentioned in our referenceURL section.
referenceId must not be active prior to this operation i.e., it must not have been used before this operation.
De-duplication must not be performed in this operation.
MOSIP will provide biometric data in CBEFF format to ABIS as a response of referenceURL and the data will be encrypted and encoded as mentioned below.

Request and Response Structure for Insert

Insert Request

{
  "id": "mosip.abis.insert",
  "version": "1.1",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "referenceURL": "https://{base_url}/v1/datashare/get/mpolicy-default-abis/mpartner-default-abis/mpartner-default-abismpolicy-default-abis20210205062412BlQo0rJB"
}

Success Response

{
  "id": "mosip.abis.insert",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Failure Response

{
  "id": "mosip.abis.insert",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "7"
}

Reference URL

The reference URL is MOSIP's datashare URL which is generated based on a policy defined by MOISP's adopter.

The referenceURL is authenticated and authorized; ABIS needs to send a JWT token inside the request header COOKIE.
The referenceURL will be active for a certain time as decided by the MOSIP adopter.
The data sent in the referenceURL will be encrypted.

Authentication Token

As mentioned above in order to access the request URL the ABIS system needs to send a JWT token inside the request header COOKIE. In order to get the token ABIS needs to call MOSIP's AuthN & AuthZ API with Client ID & Secret Key by passing the credentials (clientid, secretkey and appid) which would be provided by the System Integrator (SI).

Below are the sample API details for getting the authentication token. More details about the API are available in our AuthN & AuthZ document.

Sample Request URL

POST https://{base_url}/v1/authmanager/authenticate/clientidsecretkey

Sample Request Body

{
  "id": "string",
  "metadata": {},
  "request": {
    "appId": "regproc",
    "clientId": "mosip-regproc-client",
    "secretKey": "abc123"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

Sample Response

Response Cookie:

Set-Cookie 
authorization: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJyanpjdUZPTmpBLWZRRDZYVVpYeFlldk5UZWtYcnZKVXN1RG5TeHJjZ0tZIn0.eyJqdGkiOiI2Yzg0ZDMyNi04NjZhLTRmZTQtOGJiMy02NGY0YWVjNmZiZDAiLCJleHAiOjE2MDk5NDg3NTAsIm5iZiI6MCwiaWF0IjoxNjA5OTEyNzUwLCJpc3MiOiJodHRwczovL3FhMi5tb3NpcC5uZXQva2V5Y2xvYWsvYXV0aC9yZWFsbXMvbW9zaXAiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiODdmMDU3NjQtNzg5ZC00ZTZiLTljMWUtYzU2YmJkYzI5NTYzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibW9zaXAtYWJpcy1jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiNjZjMjBiMy03OTY1LTQ0ZDUtODg3Ny00Zjk2MDNlNzI5OTEiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHBzOi8vcWEyLm1vc2lwLm5ldCJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7Im1vc2lwLWFiaXMtY2xpZW50Ijp7InJvbGVzIjpbInVtYV9wcm90ZWN0aW9uIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJjbGllbnRJZCI6Im1vc2lwLWFiaXMtY2xpZW50IiwiY2xpZW50SG9zdCI6IjEwLjI0NC4zLjM1IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtbW9zaXAtYWJpcy1jbGllbnQiLCJjbGllbnRBZGRyZXNzIjoiMTAuMjQ0LjMuMzUifQ.ntez3ZkbDsjWi467JVj9d3kfktbUc7e6zQhHv0bVJfmiQA0N1QGyXAiZdqZrHj3cgFo0Lft54jgEtCGZZAma8nAw9IDICet9TA2A_u5hZ3oAq6HwYMS1pWb43jx5K9RRr_Yc-hdNnma754KzHhJgU1A7e_y0m88MT_oohHpRQ16jItEfC0AUQUvOAsxPwn-mmhu4uFFEq9e05ftBDIEBr24t-8feWN92uCJVMrSYHHjFL2ayg03I4Zkw1IupfLa-HACIlIToUmAk00aPxLtyWMFpOHVcLKBS2i9gEeqCEiUzklwuEp0B4aCqk5_M-Ng2X6VcGsCUJ8ACWRG4lCQQYA

{
  "id": "string",
  "version": "string",
  "responsetime": "2021-02-05T06:31:36.885Z",
  "metadata": null,
  "response": {
    "status": "Success",
    "message": "Clientid and Token combination had been validated successfully"
  },
  "errors": null
}

DataShare URL

Below is the sample API detail for reference URL.

Sample Request URL

GET https://{base_url}/v1/datashare/get/mpolicy-default-abis/mpartner-default-abis/mpartner-default-abismpolicy-default-abis20210205062412BlQo0rJB

Sample Encrypted Response

The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions

The data downloaded would be URL-safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two Parts after splitting using #KEY_SPLITTER#.

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1

#KEY_SPLITTER#

Block 2

Block 1:

Block 1, i.e. the encrypted key data is again split into three parts,

The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.
The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.
The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

Block 2, i.e. the encrypted actual data is again split into two parts,

The 1st part is the random 32 bytes which will be used as AAD in AES encryption(first 32 bytes). From this 32 bytes AAD data, the first 12 bytes is IV/Nonce.
The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

Note: In Java 11, PKCS5Padding serves as a synonym for NoPadding in GCM mode encryption. Conversely, in Java 17, the synonym PKCS5Padding has been eliminated, and it is now mandatory to exclusively use NoPadding. Consequently, if data is encrypted using PKCS5Padding in Java 11, it will be decrypted with NoPadding in Java 17.

The structure of the encrypted data downloaded from referenceURL in MOSIP 1.1.5.5 or prior versions

The data downloaded would be base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two Parts after splitting using #KEY_SPLITTER#.

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1

#KEY_SPLITTER#

Block 2

Block 1:

Block 1, i.e. the encrypted key data is again split into two parts,

The first part is the Certificate Thumbprint i.e. the key identifier which is the first 32 bytes in Block 1.
The second part is the Encrypted Random AES Key which is encrypted with RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

Block 2, i.e. the encrypted actual data is again split into two parts,

The 1st part is the Encrypted data, encrypted using AES GCM PKCS5Padding.
The 2nd part is IV/Nonce i.e. the last 32 bytes appended after encrypted data.

Sample Response after Decryption

<?xml version="1.0" encoding="UTF-8"?>
<BIR xmlns="http://standards.iso.org/iso-iec/19785/-3/ed-2/">
    <BIRInfo>
        <Integrity>false</Integrity>
    </BIRInfo>
    <!-- right index finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.209Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right middle finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right ring finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right little finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left index finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left middle finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left ring finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left little finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right thumb finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left thumb finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- face -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>8</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Face</Type>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right iris -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Right</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left iris -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Left</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
</BIR>

Sample Response in case of Authentication Failure

{
  "id": null,
  "version": null,
  "responsetime": "2021-02-05T06:29:48.257Z",
  "metadata": null,
  "response": null,
  "errors": [
    {
      "errorCode": "KER-ATH-401",
      "message": "Authentication Failed"
    }
  ]
}

All Possible Error codes and Messages from Datashare URL

Error Code

Error Message

DAT-SER-003

File does not exists or File is empty

DAT-SER-006

Data share not found

DAT-SER-006

Data share usage expired

KER-ATH-401

Authentication Failed

KER-ATH-403

Forbidden

Please note that for all the functional failures MOSIP sends a response code 200.

Identify

All Insert requests added to the queue earlier must be serviced by ABIS when performing an Identify request.
Identify request provides a 1:N comparison. The given input is compared either against the gallery passed or if the gallery is not specified the entire database.
The input for comparison can be provided by referenceID or referenceURL.
- If the referenceID is given it is used as the preferred option. The given referenceID must be existing in the ABIS database else ABIS will throw an error.
- If the referenceID is omitted or NULL and the referenceURL is passed the ABIS retrieves the biometrics provided in the referenceURL and compares the same against either a gallery or its database.
- If in case, both referenceID and referenceURL are missing ABIS throws an error.

We are not using the referenceURL in Identify request for our current implementation. Hence, it will be an empty string for Identify request. MOSIP adopters can have customized workflows where the referenceURL can be used.

Identify requests should give to all candidates which are considered as a match based on ABIS thresholds.
This request should not match against referenceID that is not in the reference database.
The response now has a section for analytics that contains key-value pairs. Values can be JSON objects also. The contents of the analytics section will be agreed upon by the MOSIP adopter with the ABIS provider. Scores are also moved to this section and are not mandatory response parameters anymore.
Ordering or ranking of results is not explicitly specified and can be agreed upon between the MOSIP adopter and the ABIS provider.
The flags section of the request can be used to customize or control ABIS behaviour by sending specific key-value pairs.
"targetFPIR" or "maxResults" are examples of such flags that can alter ABIS behaviour. These are optional attributes for MOSIP during an identify request. MOSIP expects the adopters to define these parameters based on the accuracy expectations and workflow requirements. These can be set at the ABIS configuration level and need not be part of the individual request at all.

To give an example, please find the following calculation for targetFPIR - which is the error rate at which identification requests are expected to return a non-empty candidate list.

round (-10 * log10 (target false positive identification rate))

With this calculation:

Target False Positive Identification Rate

targetFPIR

1 in 1,000

1 in 10,000

1 in 100,000

Identify Request

{
  "id": "mosip.abis.identify",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "referenceURL": "",//will be an empty string, if not used
  "flags": { //optional
    //maxResults is an example and not a prescribed flag
	"maxResults": "10", 
	//targetFPIR is an example and not a prescribed flag
	"targetFPIR": "30",
    //there can be more following this	
	"flag1": "value1",
	"flag2": "value2" 
  },
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "2abe7b7d-b58a-4466-a006-c79297281123"
      }, 
      {
        "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456"
      }, 
      {
        "referenceId": "3bce7b7d-b58a-4466-a006-c79297281678"
      }, 
      {
        "referenceId": "5cce7b7d-b58a-4466-a006-c79297281098"
      }, 
      {
        "referenceId": "2cce7b7d-b58a-4466-a006-c79297281321"
      } 
    ]
  }
}

Success Response

{
  "id": "mosip.abis.identify",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456",
        "analytics": {
		  //internalScore is an example and not prescribed
		  "internalScore": "112", 
		  //confidence is an example and not prescribed
          "confidence": "90",
		  //there can be more following this	
		  "key1": "value1",
		  "key2": "value2"
        },
		// modality wise analytics
        "modalities": [ 
          {
            "biometricType": "FIR",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          },
		  {
            "biometricType": "IIR",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          },
		  {
            "biometricType": "FID",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          }
        ]
      }
    ]
    "analytics": {
      //This is an optional section
      //Data in this section can be agreed upon between the MOSIP adopter and the ABIS Provider
	}
  }
}

Failure Response

{
  "id": "mosip.id.identify",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "7"
}

Delete

Removes only the entry referred by the referenceId.
This operation can be used to remove duplicates found by Identify.

Delete Request

{
  "id": "mosip.abis.delete",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456"
}

Success response

{
  "id": "mosip.abis.delete",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Failure response

{
  "id": "mosip.abis.delete",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "1"
}

Ping

A Ping request should respond with a response on the liveness of the ABIS system.

Ping Request

{
  "id": "mosip.abis.ping",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success response

{
  "id": "mosip.abis.ping",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Pending Jobs

ABIS responds with the count of requests that are still pending.

Pending Jobs Request

{
  "id": "mosip.abis.pendingJobs",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success Response

{
  "id": "mosip.abis.pendingJobs",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "jobscount": "10",
  "returnValue": "1"
}

Reference Count

ABIS will send a count of records in the reference database

Reference Count Request

{
  "id": "mosip.abis.referenceCount",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success Response

{
  "id": "mosip.abis.referenceCount",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "count": "10",
  "returnValue": "1"
}

References

Biometric Specification to know about the biometric specification in MOSIP.
CBEFF XML to know how MOSIP stores biometric data.
Authentication and Authorization API to get the JWT token.
MOSIP's de-duplication process for details about the De-Duplication process in MOSIP.

Biometric SDK

Overview

The BioSDK diagram illustrates how MOSIP integrates biometric devices for registration and authentication. It shows the flow of biometric data from capture devices through the Secure Biometric Interface (SBI) to the BioSDK, which performs quality checks, deduplication, and operator authentication.

For registration, signed biometrics are sent to the MOSIP backend, where the BioSDK ensures data quality, ABIS handles deduplication, and ID Auth manages 1:1 matching. During authentication, encrypted biometrics are verified via the authentication app. Device management, including registration, deregistration, and key rotation, is handled by the Device Management Server.

Applications

Registration Client.
Backend quality check.
Biometric authentication during onboarding (internal auth).
ID Authentications.

Biometric SDK library

The library is used by the Registration Client to perform 1:N match, segmentation, extraction, etc. For more information on integration with Registration Client, refer to the Registration Client Biometric SDK Integration Guide.

A simulation of this library is available as Mock BioSDK. The same is installed in the MOSIP sandbox.

Biometric SDK service

For 1:1 match and quality check of biometrics at the MOSIP backend, the BioSDK must be running as a service that can be accessed by Registration Processor and IDA Internal Services. The service exposes REST APIs specified here.

A simulation (mock) service has been provided. The mock service loads mock BioSDK internally on the startup and exposes the endpoints to perform 1:N match, segmentation, and extraction as per IBioAPI.

The service may be packaged as a docker running inside the MOSIP Kubernetes cluster or running separately on a server. The scalability of this service must be taken care of depending on the load on the system, i.e., the rate of enrolment and ID authentication.

API

BioSDK library: IBioAPIV2
BioSDK service: TBD.

Testing kit

BioSDK server request/response may be tested using the BioSDK testing kit.

Configuration

The following properties in application-default.properties needs to be updated to integrate the BioSDK library and service with MOSIP.

mosip.fingerprint.provider=io.mosip.kernel.bioapi.impl.BioApiImpl
mosip.face.provider=io.mosip.kernel.bioapi.impl.BioApiImpl
mosip.iris.provider=io.mosip.kernel.bioapi.impl.BioApiImpl
mosip.ida.biosdk-service.url=http://mock-biosdk-service.default:80
mosip.regproc.biosdk-service.url=http://mock-biosdk-service.default:80
mosip.idrepo.biosdk-service.url=http://mock-biosdk-service.default:80

Biometric Devices

Overview

Biometric devices capture individuals' biometric data (fingerprint, iris scan, photo) and send it to a registration client or authentication client (app). The functional architecture of the various entities involved is shown below.

Device types

Purpose

Type

Subtype*

Certification

Specification

Registration

Fingerprint

Slap scanner

SBI 1.0

Registration

Iris

Double eye scanner

SBI 1.0

Registration

Face

Camera

SBI 1.0

Authentication

Fingerprint

Single finger scanner

SBI 2.0

Authentication

Iris

Single eye scanner

SBI 2.0

Authentication

Face

Camera

SBI 2.0

* An adopter may choose to have different subtypes, however, the certification needs to be adhered to.

Enrolment flow

Authentication flow

Compliance test kit

Compliance of a device may be tested using an Compliance Tool Kit (CTK).

Devices calculator

The following calculator may be used to estimate the number of devices required for a rollout.

MOSIPDevicesCalculator

Partners

Providers of biometric devices are Partners of MOSIP and need to be onboarded to a given deployment of MOSIP. Specifically,

FTM

Overview

The Foundational Trust Module (FTM) is created using a secure microprocessor capable of performing all required biometric processing and secure storage of keys. The foundational device trust would satisfy the below requirements.

The module has the ability to securely generate, store, and process cryptographic keys.
Generation of asymmetric and symmetric keys with TRNG.
The module has the ability to protect keys from extraction.
The module has to protect the keys from physical tampering, temperature, frequency, and voltage-related attacks.
The module could withstand Hardware cloning.
The module could withstand probing attacks
The module provides memory segregation for cryptographic operations and protection against buffer overflow attacks
The module provides the ability to withstand cryptographic side-channel attacks like Differential Power analysis attacks, and timing attacks.
CAVP validated the implementation of the cryptographic algorithm.
The module has the ability to perform a cryptographically valid, secure boot.
The module has the ability to run trusted applications.

The foundational device trust derived from this module is used to enable trust-based computing for biometric capture. The foundational device trust module provides a trusted execution environment based on the following:

Secure Boot
- Ability to cryptographically verify code before execution.
- Ability to check for integrity violations of the module or device.
- Halt upon failure.
- The ability to securely upgrade and perform forward-only upgrades to thwart downgrade attacks.
- SHA256 hash equivalent or above should be used for all hashing requirements
- All root of trust is provisioned upon first boot or before.
- All upgrades would be considered successful only after a successful boot with proper hash and signature verification.
- The boot should fail upon hash or signature failures and never operate in an intermediary state.
- A maximum of 10 failed attempts should lock the upgrade process and brick the device. However, chip manufacturers can decide to be less than 10.
Secure application
- Ability to run applications that are trusted.
- Protect against the downgrading of applications.
- Isolated memory to support cryptographic operations.
- All trust is anchored during the first boot and not modifiable.

Certification

The FTM should have at least one of the following certifications in each category to meet the given requirement.

Category: Cryptographic Algorithm Implementation

CAVP (RSA, AES, SHA256, TRNG (DRBGVS), ECC)

Category: FTM Chip

(ONE of the following certifications)

FIPS 140-2 L3 or above
PCI PTS 5 or above (Pre-certified)
PCI - PED 2.0 or above (Pre-Certified)
One of the following Common Criteria (CC) certification
- https://www.commoncriteriaportal.org/files/ppfiles/pp0035a.pdf
- https://www.commoncriteriaportal.org/files/ppfiles/pp0084a_pdf.pdf

System/Device Level Tamper (optional)

System/Device Level Tamper Responsiveness is recommended (not mandatory). In this case, FTM should be capable of showcasing Tamper Responsiveness (keys must be erased) against a tamper at the system/device level.

Threats to Protect

The FTM should protect against the following threats.

Hardware cloning attacks - Ability to protect against attacks that could result in a duplicate with keys.
Hardware Tamper attacks
- Physical tamper - No way to physically tamper and obtain its secrets.
- Voltage & frequency related attacks - Should shield against voltage leaks and should prevent low voltage. The FTM should always be in either the state operational normally or inoperable. The FTM should never be operable when its input voltages are not met.
- Temperature attacks on the crypto block - Low or High the FTM are expected to operate or reach an inoperable state. No state in between.
Differential Power Analysis attack.
Probing attacks - FTM should protect its surface area against any probe-related attacks.
Segregation of memory for execution of cryptographic operation (crypto block should be protected from buffer overflow type attacks).
Vulnerability of the cryptographic algorithm implementation.
Attacks against secure boot & secure upgrade.
TEE/Secure processor OS attack.

Foundational Trust Module Identity

Upon the FTM provider's approval by the MOSIP adopters, the FTM provider would submit a self-signed public certificate to the adopter. Let us call this the FTM root. The adopter would use this certificate to seed their device's trust database. The FTM root and their key pairs should be generated and stored in FIPS 140-2 Level 3 or more compliant devices with no possible mechanism to extract the keys. The foundational module upon its first boot is expected to generate a random asymmetric key pair and provide the public part of the key to obtain a valid certificate. The FTM provider would validate to ensure that the chip is unique and would issue a certificate with the issuer set to FTM root. The entire certificate issuance would be in a secured provisioning facility. Auditable upon notice by the adopters or its approved auditors. The certificate issued to the module will have a defined validity period as per the MOSIP certificate policy document defined by the MOSIP adopters. This certificate and private key within the FTM chip are expected to be in its permanent memory.

The validity of the chip certificate can not exceed 20 years from the date of manufacturing.

The FTM should have at least one of the following certifications in each category to meet the given requirement.

Secure Provisioning

Secure provisioning applies to both the FTM and the Device providers.

The devices and FTM should have a mechanism to protect against fraudulent attempts to create or replicate.
The device and FTM trust should be programmed in a secure facility which is certified by the respective MOSIP adopters.
The organization should have a mechanism to segregate the FTMs and Devices built for MOSIP using a cryptographically valid and repeatable process.
All debug options within the FTM or device should be disabled permanently
All key creations needed for provisioning should happen automatically using FIPS 140-2 Level 3 or higher devices. No individual or group or organization should have a mechanism to influence this behaviour.
Before the devices/FTM leaves the secure provisioning facility all the necessary trust should be established and should not be re-programmable.

As there is no adopter-specific information being exchanged at the management server or the FTM provisioning server, there are no mandates from MOSIP where these are located globally. However, the adopter is recommended to have an audit and contractual mechanisms to validate the compliance of these components at any point in time.

Biometric Specification

Introduction

Biometric images for various modalities are captured, represented, and exchanged according to the specifications outlined below.

Change History

The below table outlines the updates and modifications made to the biometric specifications over time.

Image formats

Fingerprint

Captures and compresses fingerprint images for registration and authentication.

Please refer to ISO 19794-4:2011 Specifications.

Iris

Captures high-quality iris images with optional cropping and compression.

Please refer to ISO 19794-6:2011 Specifications.

Face Capture

Captures facial images with lossless or lossy compression for identification.

Please refer to ISO 19794-5:2011 Specifications.

Capture Time across modalities should be less than 4 Seconds (time taken for providing a final capture response to the calling application, when the biometrics are well placed on the sensors)

We recommend that countries look at ergonomics, accessibility, ease of usage, and common availability of devices while choosing devices for use in registration and authentication scenarios.

XML Container

MDS Specification

Introduction & Background

Objective

The objective of this specification document is to establish the technical and compliance standards/ protocols that are necessary for a biometric device to be used in MOSIP solutions.

Target Audience

This is a biometric device specification document and aims to help the biometric device manufacturers, their developers, and their designers in building MOSIP-compliant devices. It is assumed that the readers are familiar with MOSIP registration and authentication services.

MOSIP Devices

All devices that collect biometric data for MOSIP should operate within the specification of this document.

Revision History

Version

State

Date

Changes

0.9.2

Frozen

Aug-2019

0.9.3

Frozen

Feb-2020

0.9.5

Draft

13-Jun-2020

0.9.5

Draft

10-Aug-2020

Signature for API to retrieve encryption certificate has been changed from GET to POST and Device Stream now supports an optional parameter - timeout

0.9.5

Draft

04-Dec-2020

In the header of JWT Signature, the key to store the type has been changed to "typ" from "type" as per JWT standards. Kindly view the digital id specification for the change.

0.9.5

Draft

26-Feb-2021

0.9.5

Draft

24-Mar-2021

0.9.5

Draft

07-Apr-2021

Device De registration API spec was updated.

0.9.5

Draft

08-Apr-2021

We will be following datetime values in ISO 8601 with format yyyy-mm-ddTHH:MM:ssZ. The same has been updated throughout the document.

0.9.5

Draft

24-May-2021

Clarification on hash and previousHash definition has been provided

0.9.5

Draft

04-Apr-2022

Register and De-register of devices have been removed from MOSIP. Device validation in MOSIP will be done via cryptography. Here onwards, registering a device will mean a device obtaining a certificate from the management server.

0.9.5

Draft

27-Jul-2022

0.9.5

Draft

24-Oct-2023

Added error code for devices in busy or not ready state. Also added validation for transactionID in request parameters.

Glossary of Terms

Device Provider - An entity that manufactures or imports the devices in their name. This entity should have legal rights to obtain an organization-level digital certificate from the respective authority in the country.
FTM Provider - An entity that manufactures or guarantees the trustworthiness of the foundational trust module. This can be the device provider as well.
Device - A hardware capable of capturing biometric information.
L1 Certified Device / L1 Device - A device certified as capable of performing encryption in line with this spec in its trusted zone.
L0 Certified Device / L0 Device - A device certified as one where the encryption is done on the host machine device driver or the MOSIP device service.
FTM Provider Certificate - A digital certificate issued to the "Foundational Trust Provider". This certificate proves that the provider has successfully gone through the required Foundational Trust Provider evaluation. The entity is expected to keep this certificate in secure possession in an HSM. All the individual FTM trust certificates are issued using this certificate as the root. This certificate would be issued by the countries in conjunction with MOSIP.
Device Provider Certificate - A digital certificate issued to the "Device Provider". This certificate proves that the provider has been certified for L0/L1 respective compliance. The entity is expected to keep this certificate in secure possession in an HSM. All the individual trust certificates are issued using this certificate as the root. This certificate is issued by the countries in conjunction with MOSIP.
Registration - The process of applying for a Foundational Id.
KYC - Know Your Customer. The process of providing consent to perform profile verification and update.
Auth - The process of verifying one’s identity.
FPS - Frames Per Second
Management Server - A server run by the device provider to manage the life cycle of the biometric devices.
Device Registration - The process of a device obtaining a certificate from the management server.
Signature - All signatures should be as per RFC 7515.
header in signature - The header in the signature means the attribute with "alg" set to RS256 and x5c set to base64encoded certificate.
payload is the byte array of the actual data, always represented as base64urlencoded.
signature - base64urlencoded signature bytes
ISO format timestamp | ISO 8601 with the format yyyy-mm-ddTHH:MM:ssZ (Example: 2020-12-08T09:39:37Z). This value should be in UTC (Coordinated Universal Time).

Device Specification

The MOSIP device specification provides compliance guidelines devices for that to work with MOSIP. The compliance is based on device capability, trust and communication protocols. A MOSIP-compliant device would follow the standards established in this document. It is expected that the devices are compliant with this specification and tested and validated. The details of each of these are outlined in the subsequent sections.

Device Capability

The MOSIP-compliant device is expected to perform the following,

Should have the ability to collect one or more biometric
Should have the ability to sign the captured biometric image or template.
Should have the ability to protect secret keys
Should have no mechanism to inject the biometric

Base Specifications for Devices

For details about biometric data specifications please view the page MOSIP Biometric Specification.

We recommend that countries look at ergonomics, accessibility, ease of usage, and common availability of devices while choosing devices for use in registration and authentication scenarios.

Device Trust

MOSIP-compliant devices provide a trusted environment for the devices to be used in registration, KYC and AUTH scenarios. The trust level is established based on the device support for trusted execution.

L1 - The trust is provided by a secure chip with a secure execution environment.
L0 - The trust is provided at the software level. No hardware-related trust exists. This type of compliance is used in controlled environments.

Foundational Trust Module (FTM)

The foundational trust module would be created using a secure microprocessor capable of performing all required biometric processing and secure storage of keys. The foundational device trust would satisfy the below requirements.

The module can securely generate, store and process cryptographic keys.
Generation of asymmetric keys and symmetric keys with TRNG.
The module can protect keys from extraction.
The module has to protect the keys from physical tampering, temperature, frequency and voltage-related attacks.
The module could withstand Hardware cloning.
The module could withstand probing attacks
The module provides memory segregation for cryptographic operations and protection against buffer overflow attacks
The module provides the ability to withstand cryptographic side-channel attacks like Differential Power analysis attacks, Timing attacks.
CAVP validated the implementation of the cryptographic algorithm.
The module can perform a cryptographically validatable secure boot.
The module can run trusted applications.

Secure Boot
- Ability to cryptographically verify code before execution.
- Ability to check for integrity violations of the module/device.
- Halt upon failure.
- Ability to securely upgrade and perform forward-only upgrades, to thwart downgrade attacks.
- SHA256 hash equivalent or above should be used for all hashing requirements
- All root of trust is provisioned upon first boot or before.
- All upgrades would be considered a success only after the successful boot with proper hash and signature verification.
- The boot should fail upon hash/signature failures and would never operate in an intermediary state.
- A maximum of 10 failed attempts should lock the upgrade process and brick the device. However, chip manufacturers can decide to be less than 10.
Secure application
- Ability to run applications that are trusted.
- Protect against the downgrading of applications.
- Isolated memory to support cryptographic operations.
- All trust is anchored during the first boot and not modifiable.

Certification

The FTM should have at least one of the following certifications in each category to meet the given requirement.

Category: Cryptographic Algorithm Implementation

CAVP (RSA, AES, SHA256, TRNG (DRBGVS), ECC)

{% hint style="info" %} The supported algorithm and curves are listed here {% endhint %}

Category: FTM Chip

(ONE of the following certifications)

FIPS 140-2 L3 or above
PCI PTS 5 or above (Pre-certified)
PCI - PED 2.0 or above (Pre-Certified)
One of the following Common Criteria (CC) certification
- https://www.commoncriteriaportal.org/files/ppfiles/pp0035a.pdf
- https://www.commoncriteriaportal.org/files/ppfiles/pp0084a_pdf.pdf

System/Device Level Tamper (optional)

Threats to Protect

The FTM should protect against the following threats.

Hardware cloning attacks - Ability to protect against attacks that could result in a duplicate with keys.
Hardware Tamper attacks
- Physical tamper - No way to physically tamper and obtain its secrets.
- Voltage & frequency related attacks - Should shield against voltage leaks and should prevent low voltage. The FTM should always be in either the state operational normally or inoperable. The FTM should never be operable when its input voltages are not met.
- Temperature attacks on the crypto block - Low or High the FTM are expected to operate or reach an inoperable state. No state in between.
Differential Power Analysis attack.
Probing attacks - FTM should protect its surface area against any probe-related attacks.
Segregation of memory for execution of cryptographic operation (crypto block should be protected from buffer overflow type attacks).
Vulnerability of the cryptographic algorithm implementation.
Attacks against secure boot & secure upgrade.
TEE/Secure processor OS attack (if applicable).

Foundational Trust Module Identity

Upon FTM provider approval by the MOSIP adopters, the FTM provider would submit a self-signed public certificate to the adopter. Let us call this the FTM root. The adopter would use this certificate to seed their device's trust database. The FTM root and their key pairs should be generated and stored in FIPS 140-2 Level 3 or more compliant devices with no possible mechanism to extract the keys. The foundational module upon its first boot is expected to generate a random asymmetric key pair and provide the public part of the key to obtain a valid certificate. The FTM provider would validate to ensure that the chip is unique and would issue a certificate with the issuer set to an FTM certificate chain. The entire certificate issuance would be in a secured provisioning facility. Auditable upon notice by the adopters or its approved auditors. The certificate issued to the module will have a defined validity period as per the MOSIP certificate policy document defined by the MOSIP adopters. This certificate and private key within the FTM chip is expected to be in its permanent memory.

{% hint style="info" %} The validity of the chip certificate can not exceed 20 years from the date of manufacturing. {% endhint %}

Device

MOSIP devices are most often used to collect biometrics. The devices are expected to follow the specification for all levels of compliance and their usage. The MOSIP devices fall under the category of Trust Level 3 (TL3) as defined in MOSIP architecture. At TL3 device is expected to be whitelisted with a fully capable PKI and secure storage of keys at the hardware.

L0 - A device can obtain L0 certification when it uses a software-level cryptographic library with no secure boot or FTM. These devices will follow different device identities and the same would be mentioned as part of exception flows.
L1 - A device can obtain L1 certification when it is built in a secure facility with one of the certified FTM.

Device Identity

All devices that connect to MOSIP must be identifiable. MOSIP believes in cryptographic Identity as its basis for trust.

Physical ID

An identification mark that shows MOSIP compliance and a readable unique device serial number (minimum of 12 alphanumeric characters) make and model. The same information has to be available over a 2D QR Code or Barcode. This is to help field support and validation.

Digital ID

A digital device ID in MOSIP would be a signed JSON (RFC 7515) as follows:

{
  "serialNo": "Serial number",
  "make": "Make of the device",
  "model": "Model of the device",
  "type": "Type of the biometric device",
  "deviceSubType": "Subtypes of the biometric device",
  "deviceProvider": "Device provider name",
  "deviceProviderId": "Device provider id",
  "dateTime": "Current datetime in ISO format"
}

Signed with the JSON Web Signature (RFC 7515) using the "Foundational Trust Module" Identity key, this data is the fundamental identity of the device. Every MOSIP-compliant device will need the foundational trust module.

The only exception to this rule is for the L0-compliant devices that have the purpose of "Registration". L0 devices would sign the Digital Id with the device key.

A signed digital ID would look as follows:

"digitalId": "base64urlencoded(header).base64urlencoded(payload).base64urlencoded(signature)"

The header in the digital id would have:

"alg": "RS256",
"typ": "JWT",
"x5c": "<Certificate of the FTM chip, If in case the chain of certificates are sent then the same will be ignored">

MOSIP assumes that the first certificate in the x5c is the FTM's chip public certificate issued by the FTM root certificate.

An unsigned digital ID would look as follows:

"digitalId": "base64urlencoded(payload)"

Payload is the Digital ID JSON object.

{% hint style="info" %} For an L0 unregistered device, the digital id will be unsigned. In all other scenarios, except for a discovery call, the digital ID will be signed either by the chip key (L1) or the device key (L0). {% endhint %}

Accepted Values for Digital ID

Parameters

Description

serialNo

Serial number of the device.

make

Brand name.

model

Model of the device.

type

Currently allowed values for device type are "Finger", "Iris" or "Face".
More types can be added based on Adopter's implementation.

deviceSubType

The device subtype is based on the device type.
For Finger - "Slap", "Single" or "Touchless"
For Iris - "Single" or "Double"
For Face - "Full face"

deviceProvider

Name of the device provider.
The device provider should be a legal entity in the country.

dateTime

The current time during the issuance of the request.
This is in ISO format.

Keys

List of keys used in the device and their explanation.

Device Key

Each biometric device would contain an authorized private key after the device registration. This key is rotated frequently based on the requirement of the respective adopter of MOSIP. By default, MOSIP recommends a 30-day key rotation policy for the device key. The device keys are created by the device providers inside the FTM during a successful registration. The device keys are used for signing the biometric. More details of the signing and its usage will be here. This key is issued by the device provider and the certificate of the device key is issued by the device provider key which in turn is issued by the MOSIP adopter after approval of the device provider's specific model.

FTM Key

The FTM key is the root of the identity. This key is created by the FTM provider during the manufacturing/provisioning stage. This is a permanent key and would never be rotated. This key is used to sign the Digital ID.

MOSIP Key

The MOSIP key is the public key provided by the MOSIP adopter. This key is used to encrypt the biometric. Details of the encryption are listed below. We recommend rotating this key every 1 year.

Device Service - Communication Interfaces

The section explains the necessary details of the biometric device connectivity, accessibility, discover-ability and protocols used to build and communicate with the device.

The device should implement only the following set of APIs. All the APIs are independent of the physical layer and the operating system, with the invocation being different across operating systems. While the operating system names are defined in this spec a similar technology can be used for unspecified operating systems. It is expected that the device service ensures that the device is connected locally to the host.

Device Discovery

Device discovery would be used to identify MOSIP-compliant devices in a system by the applications. The protocol is designed as a simple plug-and-play with all the necessary abstractions to the specifics.

Device Discovery Request

{
  "type": "type of the device"
}

Accepted Values for Device Discovery Request

type - "Biometric Device", "Finger", "Face", "Iris"

{% hint style="info" %} "Biometric Device" - is a special type and is used in case you are looking for any biometric device. {% endhint %}

Device Discovery Response

[
  {
    "deviceId": "Internal ID",
    "deviceStatus": "Device status",
    "certification": "Certification level",
    "serviceVersion": "Device service version",
    "deviceSubId": ["Array of supported device sub Ids"],
    "callbackId": "Base URL to reach the device",
    "digitalId": "Unsigned Digital ID of the device",
    "deviceCode": "Same as serialNo in digital ID",
    "specVersion": ["Array of supported MDS specification version"],
    "purpose": "Auth or Registration or empty if not registered",
    "error": {
      "errorCode": "101",
      "errorInfo": "Invalid JSON Value Type For Discovery.."
    }
  },
  ...
]

Accepted Values for Device Discovery Response

Parameters

Description

deviceStatus

Allowed values are "Ready", "Busy", "Not Ready" or "Not Registered".

certification

Allowed values are "L0" or "L1" based on the level of certification.

serviceVersion

Device service version.

deviceId

Internal ID to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

callbackId

This differs as per the OS.
In the case of Linux and windows operating systems, it is an HTTP URL.
In the case of android, it is the intent name.
In IOS, it is the URL scheme.
The call-back URL takes precedence over future requests as a base URL.

digitalId

Digital ID as per the Digital ID definition but it will not be signed.

deviceCode

Same as serialNo in digital ID.

specVersion

An array of supported MDS specification versions. The array element zero will always contain the spec version using which the response is created.

purpose

Purpose of the device in the MOSIP ecosystem. Allowed values are "Auth" or "Registration".

error

error.errorCode

error.errorInfo

Description of the error that can be displayed to the end user. Multi-lingual support.

{% hint style="info" %}

The response is an array that we could have a single device enumerating with multiple biometric options.
The service should ensure to respond only if the type parameter matches the type of device or the type parameter is a "Biometric Device".
This response is a direct JSON as shown in the response. {% endhint %}

Windows/Linux

All the device API will be based on the HTTP specification. The device always binds to any of the available ports ranging from 4501 - 4600. The IP address used for binding has to be 127.0.0.1 and not localhost.

The applications that require access to MOSIP devices could discover them by sending the HTTP request to the supported port range. We will call this port the device_service_port in the rest of the document.

HTTP Request:

MOSIPDISC http://127.0.0.1:<device_service_port>/device
HOST: 127.0.0.1: <device_service_port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:http://127.0.0.1:<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %}

The payloads are JSON in both cases and are part of the body.
CallbackId would be set to the http://127.0.0.1:<device_service_port>/. So, the caller will use the respective HTTP verb/method and the URL to call the service. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Device Info

The device information API would be used to identify the MOSIP-compliant devices and their status by the applications.

Device Info Request

Accepted Values for Device Info Request

Device Info Response

[
  {
    "deviceInfo": {
      "deviceStatus": "Current status",
      "deviceId": "Internal ID",
      "firmware": "Firmware version",
      "certification": "Certification level",
      "serviceVersion": "Device service version",
      "deviceSubId": ["Array of supported device sub Ids"],
      "callbackId": "Baseurl to reach the device",
      "digitalId": "Signed digital id as described in the digital id section of this document.",
      "deviceCode": "Same as serialNo in digital ID",
      "env": "Target environment",
      "purpose": "Auth or Registration",
      "specVersion": ["Array of supported MDS specification version"],
    },
    "error": {
      "errorCode": "101",
      "errorInfo": "Invalid JSON Value "
    }
  }
  ...
]

So the API would respond in the following format.

[
  {
    "deviceInfo": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
    "error": {
      "errorCode": "100",
      "errorInfo": "Device not registered. In this case, the device info will be only base64urlencode(payload)"
    }
  }
]

Allowed values for Device Info Response

Parameters

Description

deviceInfo

The deviceInfo object is sent as JSON Web Token (JWT).
For a device which is not registered, the deviceInfo will be unsigned.
For a device which is registered, the deviceInfo will be signed using the device key.

deviceInfo.deviceStatus

This is the status of the device.
Allowed values are "Ready", "Busy", "Not Ready" or "Not Registered".

deviceInfo.deviceId

Internal Id to identify the actual biometric device within the device service.

deviceInfo.firmware

The exact version of the firmware.
In the case of L0, this is the same as serviceVersion.

deviceInfo.certification

Allowed values are "L0" or "L1" based on the level of certification.

deviceInfo.serviceVersion

The version of the MDS specification that is supported.

deviceInfo.deviceId

Internal ID to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

deviceInfo.callbackId

This differs as per the OS.
In the case of Linux and windows operating systems, it is an HTTP URL.
In the case of android, it is the intent name.
In IOS, it is the URL scheme.
The call-back URL takes precedence over future requests as a base URL.

deviceInfo.digitalId

The digital id is as per the digital id definition.
For L0 devices which is not registered, the digital id will be unsigned.
For L0 devices which are registered, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

deviceInfo.env

The target environment.
For devices that are not registered the environment is "None".
For a device that is registered, then send the environment in which it is registered.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

deviceInfo.purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

deviceInfo.specVersion

An array of supported MDS specification versions. The array element Zero will always contain the spec version using which the response is created.

error

error.errorCode

error.errorInfo

Description of the error that can be displayed to the end user. Multi-lingual support.

{% hint style="info" %}

The response is an array that we could have a single device enumerating with multiple biometric options.
The service should ensure to respond only if the type parameter matches the type of device or the type parameter is a "Biometric Device". {% endhint %}

Windows/Linux

The applications that require more details of the MOSIP devices could get them by sending the HTTP request to the supported port range. The device always binds to any of the available ports ranging from 4501 - 4600. The IP address used for binding has to be 127.0.0.1 and not localhost.

HTTP Request:

MOSIPDINFO http://127.0.0.1:<device_service_port>/info
HOST: 127.0.0.1:<device_service_port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:http://127.0.0.1:<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %} The payloads are JSON in both cases and are part of the body. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Capture

The capture request would be used to capture a biometric from MOSIP-compliant devices by the applications. The captured call will respond with success to only one call at a time. So, in case of a parallel call, the device info details are sent with the status "Busy".

Capture Request

{
  "env": "Target environment",
  "purpose": "Auth or Registration",
  "specVersion": "Expected version of the MDS spec",
  "timeout": "Timeout for capture",
  "captureTime": "Capture request time in ISO format",
  "domainUri": "URI of the auth server",
  "transactionId": "Transaction Id for the current capture",
  "bio": [
    {
      "type": "Type of the biometric data",
      "count":  "Finger/Iris count, in case of face max, is set to 1",
      "bioSubType": ["Array of subtypes"],
      "requestedScore": "Expected quality score that should match to complete a successful capture",
      "deviceId": "Internal Id",
      "deviceSubId": "Specific Device Sub Id",
      "previousHash": "Hash of the previous block"
    }
  ],
  "customOpts": {
    //Max of 50 key-value pairs. This is so that vendor-specific parameters can be sent if necessary. The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications. Vendors are free to include additional parameters and fine-tuning parameters. None of these values should go undocumented by the vendor. No sensitive data should be available in the customOpts.
  }
}

{% hint style="info" %} The count value should be driven by the count of the bioSubType for Iris and Finger. For Face, there will be no bioSubType but the count should be "1". {% endhint %}

Allowed Values for Capture Request

Parameters

Description

env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

specVersion

Expected version of MDS specification.

timeout

Max time the app will wait for the capture.
It's expected that the API will respond back before the timeout with the best frame.
All timeouts are in milliseconds.

captureTime

Time of capture in ISO format.
The time is as per the requested application.

domainUri

URI of the authentication server.
This can be used to federate across multiple providers or countries or unions.

transactionId

Unique Id of the transaction.
This is an internal Id to the application that's requesting a capture.
Different IDs should be used for every request.
The transactionId can have minimum lenght as 4 and max length as 50.
Allowed characters in transactionId are alphabets, numbers and hyphens (-).

bio.type

Allowed values are "Finger", "Iris" or "Face".

bio.count

The number of biometric data that is collected for a given type.
The device should validate and ensure that this number is in line with the type of biometric that's captured.

bio.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

bio.requestedScore

Upon reaching the quality score the biometric device is expected to auto-capture the image. If the requested score is not met, until the timeout, the best frame during the capture sequence must be captured/returned. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned below.

bio.deviceId

Internal Id to identify the actual biometric device within the device service.

bio.deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific model of the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index that always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

bio.previousHash

For the first capture, the previousHash is the SHA256 hash of an empty UTF-8 string. From the second capture the previous capture's "hash" is used as input. This is used to chain all the captures across modalities so all captures have happened for the same transaction and during the same time.

customOpts

In case, the device vendor wants to send additional parameters they can use this to send key-value pairs if necessary.
The values cannot be hard coded and have to be configured by the app's server and should be modifiable upon need by the applications.
Vendors are free to include additional parameters and fine-tune the process.
None of these values should go undocumented by the vendor.
No sensitive data should be available in the customOpts.

NFIQ v1.0 on a scale of 0-100 (quality score).

Scale

NFIQ v1.0

81 - 100

61 - 80

41 - 60

21 - 40

0 - 20

Capture Response

{
  "biometrics": [
    {
      "specVersion": "MDS spec version",
      "data": {
        "digitalId": "digital Id as described in this document",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioType": "Finger",
        "bioSubType": "UNKNOWN",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "domainUri": "URI of the auth server",
        "bioValue": "Encrypt biodata (ISO) with random 256-bit AES key (session key) and encode encrypted biodata with base64 URL safe encoding.",
        "transactionId": "Unique transaction id",
        "timestamp": "Capture datetime in ISO format",
        "requestedScore": "Floating point number to represent the minimum required score for the capture",
        "qualityScore": "Floating point number representing the score for the current capture"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
      "sessionKey": "Encrypt the session key (used to encrypt the bioValue) with MOSIP public key and encode encrypted session key with base64 URL safe encoding.",
      "thumbprint": "SHA256 representation of the certificate (HEX encoded) that was used for encryption of session key. All texts to be treated as uppercase without any spaces or hyphens.",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value"
      }
    },
    {
      "specVersion": "MDS spec version",
      "data": {
        "digitalId": "Digital Id as described in this document",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioType": "Finger",
        "bioSubType": "Left IndexFinger",
        "purpose": "Auth or Registration",
        "env": "target environment",
        "domainUri": "URI of the auth server",
        "bioValue": "Encrypt biodata (ISO) with random 256-bit AES key (session key) and encode encrypted biodata with base64 URL safe encoding.",
        "transactionId": "unique transaction id",
        "timestamp": "Capture datetime in ISO format",
        "requestedScore": "Floating point number to represent the minimum required score for the capture",
        "qualityScore": "Floating point number representing the score for the current capture"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
      "sessionKey": "Encrypt the session key (used to encrypt the biovalue) with MOSIP public key and encode encrypted session key with base64 URL safe encoding.",
      "thumbprint": "SHA256 representation of the certificate (HEX encoded) that was used for encryption of session key. All texts to be treated as uppercase without any spaces or hyphens.",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value"
      }
    }
  ]
}

Accepted Values for Capture Response

Parameters

Description

specVersion

The version of the MDS specification using which the response was generated.

data

The data object is sent as JSON Web Token (JWT).
The data block will be signed using the device key.

data.digitalId

The digital id is as per the digital id definition in JWT format.
For L0 devices, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

data.deviceCode

Same as serialNo in digital ID.

data.deviceServiceVersion

MDS version

data.bioType

Allowed values are "Finger", "Iris" or "Face".

data.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

data.purpose

The purpose of the device in the MOSIP ecosystem.
Allowed values are "Auth".

data.env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

data.domainUri

URI of the authentication server.
This can be used to federate across multiple providers or countries or unions.

data.bioValue

Biometric data is encrypted with a random symmetric (AES GCM) key and base-64-URL encoded. For symmetric key encryption of bioValue, (biometrics.data.timestamp XOR transactoinId) is computed and the last 16 bytes and the last 12 bytes of the results are set as the aad and the IV(salt) respectively. Look at the Authentication document to understand more about encryption.

data.transactionId

Same transactionId shared in the request should be used.

data.timestamp

Time as per the biometric device.

Note: The biometric device is expected to sync its time from the management server at regular intervals so accurate time could be maintained on the device.

data.requestedScore

Floating point number to represent the minimum required score for the capture. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned above.

data.qualityScore

The floating point number represents the score for the current capture. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned above.

hash

sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)

sessionKey

The session key (used for the encryption of the biodata (ISO)) is encrypted using the MOSIP public certificate with RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING algorithm and then encode the encrypted session key with base64 URL safe encoding.

thumbprint

SHA256 representation of the certificate (HEX encoded) that was used for encryption of the session key. All texts are to be treated as uppercase without any spaces or hyphens.

error

error.errorCode

error.errorInfo

Description of the error that can be displayed to the end-user. Multi-lingual support.

The entire data object is sent in JWT format. So, the data object will look like this:

"data" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)
payload - is defined as the entire byte array of the data block.

Windows/Linux

The applications that require capturing biometric data from a MOSIP device could do so by sending the HTTP request to the supported port range.

HTTP Request:

CAPTURE [http://127.0.0.1:<device_service_port>/capture](http://127.0.0.1/capture)
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:[http://127.0.0.1](http://127.0.0.1):<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %} The payloads are JSON in both cases and are part of the body. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Device Stream

The device would open a stream channel to send live video streams. This would help when there is an assisted operation to collect biometrics. Please note the stream APIs are available only for the registration environment.

Used only for registration module-compatible devices. This API is visible only for the devices that are registered for the purpose of "Registration".

Device Stream Request

{
  "deviceId": "Internal Id",
  "deviceSubId": "Specific device sub Id",
  "timeout": "Timeout for stream"
}

Allowed Values for device Stream Request

Parameters

Description

deviceId

Internal Id to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

timeout

Max time after which the stream should close.
This is an optional parameter and by default, the value will be 5 minutes.
All timeouts are in milliseconds.

Device Stream Response

Live Video stream with a quality of 3 frames per second or more using M-JPEG.

{% hint style="info" %} The preview should have quality markings and segment markings. The preview would also be used to display an error message on the user screen. All error messages should be localized. {% endhint %}

Error Response for Device Stream

{
  "error": {
    "errorCode": "202",
    "errorInfo": "No Device Connected."
  }
}

Windows/Linux

The applications that require more details of the MOSIP devices could get them by sending the HTTP request to the supported port range.

HTTP Request:

STREAM   http://127.0.0.1:<device_service_port>/stream
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response: HTTP Chunk of frames to be displayed. Minimum frames 3 per second.

Android

For details on android specifications please view the section - Android SBI Specification.

Registration Capture

The registration client application will discover the device. Once the device is discovered the status of the device is obtained with the device info API. During the registration, the registration client sends the RCAPTURE API and the response will provide the actual biometric data in a digitally signed non-encrypted form. When the Device Registration Capture API is called the frames should not be added to the stream. The device is expected to send the images in ISO format.

The requestedScore is on a scale of 1-100 (NFIQ v2.0 for fingerprints). So, in cases where you have four fingers the average of all will be considered for the capture threshold. The device would always send the best frame during the capture time even if the requested score is not met.

The API is used by devices that are compatible with the registration module. This API should not be supported by devices that are compatible with authentication.

Registration Capture Request

{
  "env":  "Target environment",
  "purpose": "Auth or Registration",
  "specVersion": "Expected MDS spec version",
  "timeout": "Timeout for registration capture",
  "captureTime": "Time of capture request in ISO format",
  "transactionId": "Transaction Id for the current capture",
  "bio": [
    {
      "type": "Type of the biometric data",
      "count":  "Finger/Iris count, in case of face max, is set to 1",
      "bioSubType": ["Array of subtypes"], //Optional
      "exception": ["Finger or Iris to be excluded"],
      "requestedScore": "Expected quality score that should match to complete a successful capture",
      "deviceId": "Internal Id",
      "deviceSubId": "Specific device Id",
      "previousHash": "Hash of the previous block"
    }
  ],
  "customOpts": {
    //max of 50 key-value pairs. This is so that vendor-specific parameters can be sent if necessary. The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications. Vendors are free to include additional parameters and fine-tuning parameters. None of these values should go undocumented by the vendor. No sensitive data should be available in the customOpts.
  }
}

{% hint style="info" %} To capture the exception photo exception value for Iris or Finger should be sent in bio.exception for bio.type = 'Face'. ICAO checks are not mandatory here but one face must be present within the frame. {% endhint %}

Accepted Values for Registration Capture Request

Parameters

Description

env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

specVersion

Expected version of MDS specification.

timeout

Max time the app will wait for the capture.
Its expected that the API will respond back before timeout with the best frame.
All timeouts are in milliseconds.

captureTime

Time of capture in ISO format.
The time is as per the requesting application.

transactionId

Unique Id of the transaction.
This is an internal Id to the application that's requesting a capture.
Different IDs should be used for every request.
The transactionId can have minimum lenght as 4 and max length as 50.
Allowed characters in transactionId are alphabets, numbers and hyphens (-).

bio.type

Allowed values are "Finger", "Iris" or "Face".

bio.count

Number of biometric data that is collected for a given type.
The device should validate and ensure that this number is in line with the type of biometric that's captured.

bio.bioSubType

Array of bioSubType for respective biometric type.
For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType
This is an optional parameter.

bio.exception

This is an array and all the exceptions are marked.
In case exceptions are sent for face then follow the exception photo specification above.
For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb"]
For Iris: ["Left", "Right"]

bio.requestedScore

Upon reaching the quality score the biometric device is expected to auto capture the image.

bio.deviceId

Internal Id to identify the actual biometric device within the device service.

bio.deviceSubId

Allowed values are 1, 2 or 3.
The device sub id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index that always starts with 1 and increases sequentially for each sub-device present.
In case of Finger/Iris its 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

bio.previousHash

For the first capture the previousHash is the SHA256 hash of an empty UTF-8 string. From the second capture the previous capture's "hash" is used as input. This is used to chain all the captures across modalities so all captures have happened for the same transaction and during the same time.

customOpts

In case, the device vendor wants to send additional parameters they can use this to send key value pair if necessary.
The values cannot be hard coded and have to be configured by the apps server and should be modifiable upon need by the applications.
Vendors are free to include additional parameters and fine-tuning the process.
None of these values should go undocumented by the vendor.
No sensitive data should be available in the customOpts.

Registration Capture Response

{
  "biometrics": [
    {
      "specVersion": "MDS Spec version",
      "data": {
        "digitalId": "Digital id of the device as per the Digital Id definition..",
        "bioType": "Biometric type",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioSubType": "Left IndexFinger",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "bioValue": "base64urlencoded biometrics (ISO format)",
        "transactionId": "Unique transaction id sent in request",
        "timestamp": "2019-02-15T10:01:57Z",
        "requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100.",
        "qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100."
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",    
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' } "
      }
    },
    {
      "specVersion": "MDS Spec version",
      "data": {
        "deviceCode": "Same as serialNo in digital ID",
        "bioType": "Finger",
        "digitalId": "Digital id of the device as per the Digital Id definition.",
        "deviceServiceVersion": "MDS version",
        "bioSubType": "Left MiddleFinger",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "bioValue": "base64urlencoded extracted biometric (ISO format)",
        "transactionId": "Unique transaction id sent in request",
        "timestamp": "2019-02-15T10:01:57Z",
        "requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100",
        "qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' }"
      }
    }
  ]
}

Allowed Values for Registration Capture Response

Parameters

Description

specVersion

Version of the MDS specification using which the response was generated.

data

The data object is sent as JSON Web Token (JWT).
The data block will be signed using the device key.

data.bioType

Allowed values are "Finger", "Iris" or "Face".

data.digitalId

The digital id as per the digital id definition in JWT format.
For L0 devices, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

data.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

data.deviceServiceVersion

MDS Version

data.env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

data.purpose

The purpose of the device in the MOSIP ecosystem.
Allowed values are "Auth" or "Registration".

data.bioValue

Base64-URL-encoded biometrics (in ISO format)

data.transactionId

Same transactionId shared in the request should be used.

data.timestamp

Time as per the biometric device.

Note: The biometric device is expected to sync its time from the management server at regular intervals so accurate time could be maintained on the device.

data.requestedScore

Floating point number to represent the minimum required score for the capture.

data.qualityScore

Floating point number representing the score for the current capture.

hash

sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data).

error

error.errorCode

error.errorInfo

Description of the error that can be displayed to end user. Multi lingual support.

Windows/Linux

The applications that require more details of the MOSIP devices could get them by sending the HTTP request to the supported port range.

HTTP Request:

RCAPTURE  http://127.0.0.1:<device_service_port>/capture
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response: HTTP response.

Android

For details on android specifications please view the section - Android SBI Specification.

Certificates

The MOSIP server would provide the following retrieve encryption certificate API which is white-listed to the management servers of the device provider or their partners.

Retrieve Encryption Certificate Request URL

POST https://{base_url}/v1/masterdata/device/encryptioncertficates

Version: v1

Retrieve Encryption Certificate Request

{
  "id": "io.mosip.auth.country.certificate",
  "version": "certificate server API version as defined above",
  "request": {
    "data": {
      "env":  "target environment",
      "domainUri": "uri of the auth server"
    }
  },
  "requesttime": "current timestamp in ISO format"
}

The request is sent in a JWT format. So the final request will look like this:

"request": {
  "data": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
}

Accepted Values for Retrieve Certificate Request

env - Allowed values are Staging| Developer| Pre-Production | Production
domainUri - unique uri per auth providers. This can be used to federate across multiple providers or countries or unions.

Encryption Certificate Response

{
  "id": "io.mosip.auth.country.certificate",
  "version": "certificate server API version as defined above",
  "responsetime": "Current time in ISO format",
  "response": [
    {
      "certificate": "base64encoded certificate as x509 V3 format"
    }
  ]
}

The entire response is sent in a JWT format. So the final response will look like this:

"response" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"

Management Server and Management Client

Management Server Functionalities and Interactions

The management server has the following objectives.

Validate the devices to ensure they genuine devices from the respective device provider. This can be achieved using the device info and the certificates for the Foundational Trust Module.
Register the genuine device with the MOSIP device server.
Manage/Sync time between the end device and the server. The time to be synced should be the only trusted time accepted by the device.
Ability to issue commands to the end device for
1. De-registration of the device (Device Keys)
2. Collect device information to maintain, manage, support and upgrade a device remotely.
A central repository of all the approved devices from the device provider.
Safe storage of keys using HSM FIPS 140-2 Level 3. These keys are used to issue the device certificate upon registration. The Management Server is created and hosted by the device provider outside of MOSIP software. The communication protocols between the MDS and the Management Server can be decided by the respective device provider. Such communication should be restricted to the above-specified interactions only. No transactional information should be sent to this server.
Should have the ability to push updates from the server to the client devices.

{% hint style="info" %} As there is no adopter-specific information being exchanged at the management server or the FTM provisioning server, there are no mandates from MOSIP where these are located globally. However, the adopter is recommended to have an audit and contractual mechanisms to validate the compliance of these components at any point in time. {% endhint %}

Management Client

The management client is the interface that connects the device with the respective management server. The communication between the management server and its clients must be designed with scalability, robustness, performance and security. The management server may add many more capabilities than what is described here, But the basic security objectives should be met at all times irrespective of the offerings.

For better and more efficient handling of the device at large volumes, we expect the devices to auto-register to the Management Server.
All communication to the server and from the server should follow the below properties.
1. All communication is digitally signed with the approved algorithms
2. All communication to the server is encrypted using one of the approved public key cryptography (HTTPS – TLS1.2/1.3 is required with one of the approved algorithms.
3. All request has timestamps attached in ISO format to the milliseconds inside the signature.
4. All communication back and forth should have the signed digital id as one of the attributes.
It's expected that auto-registration has an absolute way to identify and validate the devices.
The management client should be able to detect the devices in a plug-and-play model.
All key rotations should be triggered from the server.
Should have the ability to detect if it's speaking to the right management server.
All upgrades should be verifiable and the client should have the ability to verify software upgrades.
Should not allow any downgrade of software.
Should not expose any API to capture biometrics. The management server should have no ability to trigger a capture request.
No logging of biometric data is allowed. (Both in the encrypted and unencrypted format)

Compliance

L1 Certified Device / L1 Device - A device certified as capable of performing encryption on the device inside its trusted zone. L0 Certified Device / L0 Device - A device certified as one where the encryption is done on the host inside its device driver or the MOSIP device service.

Secure Provisioning

Secure provisioning applies to both the FTM and the Device providers.

The devices and FTM should have a mechanism to protect against fraudulent attempts to create or replicate.
The device and FTM trust should be programmed in a secure facility that is certified by the respective MOSIP adopters.
The organization should have a mechanism to segregate the FTMs and Devices built for MOSIP using a cryptographically valid and repeatable process.
All debug options within the FTM or device should be disabled permanently
All key creations need for provisioning should happen automatically using FIPS 140-2 Level 3 or higher devices. No individual or group or organization should have a mechanism to influence this behaviour.
Before the devices/FTM leaves the secure provisioning facility all the necessary trust should be established and should not be re-programmable.

{% hint style="info" %}

As there is no adopter-specific information being exchanged at the management server or the FTM provisioning server, there are no mandates from MOSIP where these are located globally. However, the adopter is recommended to have an audit and contractual mechanisms to validate the compliance of these components at any point in time.* {% endhint %}

Compliance Level

API

Compatible

Device Discovery

L0/L1

Device Info

L0/L1

Capture

Registration Capture

L0/L1

Cryptography

Supported algorithms:

Usage

Algorithm

Key Size

Storage

Encryption of biometrics - Session Key

AES

>=256

No storage, Key is created with TRNG/DRBG inside FTM

Encryption session key data outside of FTM

RSA OAEP

>=2048

FTM trusted memory

Encryption session key data outside of FTM

ECC curve 25519

>=256

FTM trusted memory

Biometric Signature

RSA

>=2048

Key never leaves FTM created and destroyed

Biometric Signature

ECC curve 25519

>=256

Key never leaves FTM created and destroyed

Secure Boot

RSA

>=256

FTM trusted memory

Secure Boot

ECC curve 25519

>=256

FTM trusted memory

{% hint style="info" %} No other ECC curves are supported. {% endhint %}

Signature

In all the above APIs, some of the requests and responses are signed with various keys to verify the requester's authenticity. Here we have detailed the key used for signing a particular block in a request or response body of various APIs.

Request/Response

Block

Signature Key

Device Discovery Response

Device Info

NA as it will not be signed

Device Discovery Response

Digital ID

NA as it will not be signed

Device Info Response

Device Info

NA in case of unregistered device
Device Key in case of registered device

Device Info Response

Digital ID

For L0 device using device key
For L1 device using FTM chip key

Capture Response

Data

Device key is used

Capture Response

Digital ID

FTM chip key is used

Registration Capture Response

Data

Device key is used

Registration Capture Response

Digital ID

For L0 device using device key
For L1 device using FTM chip key

Android SBI Specification

This section explains the mechanism for the SBI devices to communicate in the android operating system.

Status

Draft document V 0.9

Approach

Discovery will return the appId of the discovered items. Users will be given a choice to choose one of the discovered SBI app. The selected app responds back to the intent using the default intent callback functionality.

Device Discovery

Request: io.sbi.device action: io.sbi.device data: no change type: application/json Request Schema: No change in the data structure. The serialized request data as byte array is set in the intent extras with the key as “input”. Response Schema: No change in the data structure. The serialized response data (byte array) is set in the intent extras with the key as “response”.

callbackId should be set to the appId, and can not be empty in android.

Device Info

Request: appId.Info action: appId.Info data: no change type: application/json Request Schema: No change in the data structure. The serialized request data as a byte array is set in the intent extras with the key as “input”. Response Schema: No change in the data structure. The serialized response data as a byte array is set in the intent extras with the key as “response”.

deviceInfo: callbackId should be set to the appId, can not be empty in android.

Capture

Request: appId.Capture action: appId.Capture data: no change type: application/json flag: FLAG_GRANT_READ_URI_PERMISSION Request Schema: No change in the data structure. The serialized request data as a byte array is set in the intent extras with the key as “input”. Response Schema: No change in the data structure. The response content is set as content URI “content://authority/path/id” in the intent extras as a string with the key as “response”.

URI must be invalidated right after the read.

rCapture

Request: appId.rCapture action: appId.rCapture data: no change type: application/json flag: FLAG_GRANT_READ_URI_PERMISSION Request Schema: No change in the data structure. The serialized request data as a byte array is set in the intent extras with the key as “input”. Response Schema: No change in the data structure. The response content is set as content URI “content://authority/path/id” in the intent extras as a string with the key as “response”.

The content provider should not support insert, update, delete

Device Stream

On receiving rCapture request MDS must show the stream within its UI in the foreground.

Security

Ensure to set the correct authority in the manifest and set the android:exported as “False”

Android Tab Specs

Android 9 (API Level 28) and above with hardware-backed key store.

Error Codes

Code

Message

Success

100

Device not registered

101

Unable to detect a biometric object

102

Technical error during extraction.

103

Device tamper detected

104

Unable to connect to the management server

105

Image orientation error

106

Device not found

107

Device public key expired

108

Domain public key missing

109

Requested number of biometric (Finger/IRIS) not supported

110

Device is not ready

111

Device is Busy

112

Invalid Transaction ID

5xx

Custom errors. The device provider is free to choose his error code and error messages.

CBEFF

Standards:
- ISO 19785-3
- OASIS patron format ISO/IEC JTC 1 SC 37 - biometrics
  - Patron identifier 257
  - Patron format identifier 11
- OASIS Binary Data Block Format Identifiers for Format Type ISO/IEC JTC 1 SC 37-biometrics
  - Patron identifier 257
  - BDB patron format identifier
    7 for finger image
    2 for finger minutiae
    8 for face image
    9 for iris image
MOSIP Schema is similar to OASIS Schema, with an optional attribute called others added from the LTS version.
MOSIP's CBEFF Utils can be used to create and validate CBEFF XML data.

CBEFF Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BIR xmlns="http://standards.iso.org/iso-iec/19785/-3/ed-2/">
    <BIRInfo>
        <Integrity>false</Integrity>
    </BIRInfo>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>98293c98-7b64-4f9a-a209-9cadfd8e4a1e</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.987808900Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>511e3f9c-e6f4-46b3-bc6d-193a01c6ad67</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.987808900Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJ.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>f9c11267-9018-44c2-a4d7-5bb1f1cf2555</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>8</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Face</Type>
            <Subtype></Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>5d7669c1-1f7d-4810-9cd5-5521a38be151</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>db6f289e-fb86-4c0d-818e-2fa709660caf</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Left</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJRjlqQ.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>a60f8367-0818-40de-b935-405bc6d0f810</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR\.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>b1dd9bef-0e19-42e3-b0ba-0ded02ef429b</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>ee0508b6-f42b-4a88-887b-10d71bc10ea0</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>614fb188-81c1-4190-af52-050a54fc31b5</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Right</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>971a3c27-aa02-4041-b8d8-52b402d30cd9</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>8</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>ExceptionPhoto</Type>
            <Subtype></Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>7ad51076-4d10-4f83-92a4-3954e6797355</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>b055cbde-925b-47b3-bab6-070a57c1a916</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>94</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSADAyMA\.....</BDB>
        <SB>ZXlKNE5XTWlP.....</SB>
        <others>
            <entry key="SPEC_VERSION">0.9.5</entry>
            <entry key="RETRIES">1</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">false</entry>
            <entry key="PAYLOAD">{"digitalId":"eyJ4NWMiOlsiTUlJR.....</entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>02c43091-fe1e-4b6f-acae-e2cb59c1ed9b</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>0</Score>
            </Quality>
        </BDBInfo>
        <SB></SB>
        <others>
            <entry key="SPEC_VERSION"></entry>
            <entry key="RETRIES">0</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">true</entry>
            <entry key="PAYLOAD"></entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Index>5b6e49c6-3a18-4ced-a931-d905860343fd</Index>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2022-07-27T15:29:22.988805100Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>0</Score>
            </Quality>
        </BDBInfo>
        <SB></SB>
        <others>
            <entry key="SPEC_VERSION"></entry>
            <entry key="RETRIES">0</entry>
            <entry key="FORCE_CAPTURED">false</entry>
            <entry key="EXCEPTION">true</entry>
            <entry key="PAYLOAD"></entry>
            <entry key="SDK_SCORE">0.0</entry>
        </others>
    </BIR>
</BIR>

Commons

Overview

As the name suggests, Commons refers to all the common services (also called "kernel") that are used by other modules of MOSIP. The Kernel services are listed below:

API

Refer API Documentation.

Developer Guide

To know more about the developer setups, read:

Commons Developers Guide

Overview

Commons module provides a bedrock to build and run services by providing several significant necessary technical operations. It contains common functionalities which are used by more than one module.

Below is a list of tools required in Commons:

JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)

Software setup

Download lombok.jar and settings.xml.
Unzip Apache Maven and move settings.xml to "conf" folder <apache maven unzip path>\conf.
Install Eclipse, open the lombok.jar file and then click Install/Update.

Check the Eclipse installation folder to see if the lombok.jar is added.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Source code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building

Open the project folder where pom.xml is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project.
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.
After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

Download Auth adapter and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close.
Clone mosip-config repository.
Refer Commons-DB-deploy to deploy local DB.
For integration with any of our environments, do reach out to our team.
Commons uses two property files, kernel-default and application-default, configure them accordingly. For instance

Update spring.mail.host property to update SMTP host.
Secrets can be encrypted using config server.
Update Url's in property files.(It can be either pointed to any remotely or locally deployed services).

Download kernel-config-server.jar. For windows download config-server-start.bat, linux users can run java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName} .
Run the server by opening the config-server-start.bat file.

To verify the config-server, hit the below URL http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label} for instance http://localhost:51000/config/kernel/env/master.

Initialization and utilization of module

Commons repo consists of two types of project- REST services and libraries.
Every REST service consist of bootstrap.properties file in src/main/resources.

Below properties needed to be modified in order to connect to the config server:

spring.cloud.config.uri=<config server uri>
spring.cloud.config.label=<branch of config repo>
spring.profiles.active=default

Services can be run using Run As -> Spring Boot App/Java Application.
Libraries are not meant to be run alone they are projects used by commons as well as other modules of mosip to perform commons operations.
For API documentation, refer here.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI of services can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config for instance https://dev.mosip.net/v1/authmanager/swagger-ui/index.html?configUrl=/v1/authmanager/v3/api-docs/swagger-config.
Context-path of services is present in bootstrap.properties file in src/main/resources of every service.
The API's can be tried using Postman. URLs and Body structures can be found in Swagger or curl command can be copied and imported in Postman.

Audit Manager Developers Guide

Overview

Audit Manager module provides audit-related functionalities.

Below is a list of tools required for auditing:

JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)

Software setup

1. Download lombok.jar and settings.xml.

2. Unzip Apache Maven and move settings.xml to the "conf" folder <apache maven unzip path>\conf.

4. Check the Eclipse installation folder to see if the lombok.jar is added.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Source code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building

Open the project folder where pom.xml is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project.
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.
After successfully importing of project, update the project by right-clicking on Project → Maven → Update Project.

Environment setup

1. Download Auth adapter and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close.

2. Clone mosip-config repository.

3. Refer Audit-DB-deploy to deploy local DB.

4. The audit uses two property files, kernel-default and application-default. Please configure them as needed. For instance,

Update the mosip.kernel.auditmanager-service-logs-location property to update the location of log files.
Secrets can be encrypted using config server.
Update URL's in property files.(It can be either pointed to any remotely or locally deployed services)

5. Download kernel-config-server.jar. For Windows, download config-server-start.bat, linux users can run

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName} .

6. Run the server by opening the config-server-start.bat file.

7. To verify the config-server, hit the below URL:

http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label} for instance http://localhost:51000/config/kernel/env/master.

Initialization and utilization of module

Audit REST service consist of bootstrap.properties file in src/main/resources.

Below properties needed to be modified in order to connect to the config server:

spring.cloud.config.uri=<config server uri>
spring.cloud.config.label=<branch of config repo>
spring.profiles.active=default

Services can be run using Run As -> Spring Boot App/Java Application.
For API documentation, refer here.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI of service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/auditmanager/v3/api-docs/swagger-config.
The API's can be tried using postman by copying CURL command below, updating host and importing in Postman.

curl -X 'POST' \
  'https://<host>/v1/auditmanager/audits' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "version": "string",
  "requesttime": "2022-04-20T12:23:59.300Z",
  "metadata": {},
  "request": {
    "eventId": "string",
    "eventName": "string",
    "eventType": "string",
    "actionTimeStamp": "2022-04-20T12:23:59.300Z",
    "hostName": "string",
    "hostIp": "string",
    "applicationId": "string",
    "applicationName": "string",
    "sessionUserId": "string",
    "sessionUserName": "string",
    "id": "string",
    "idType": "string",
    "createdBy": "string",
    "moduleName": "string",
    "moduleId": "string",
    "description": "string"
  }
}'

OpenID-Bridge Developers Guide

Overview

OpenID-Bridge module provides AutnN and AuthZ related funtionalities.

Below is a list of tools required in OpenID Bridge:

JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)

Software setup

Download lombok.jar and settings.xml.
Unzip Apache Maven and move settings.xml to "conf" folder <apache maven unzip path>\conf.
Install Eclipse, open the lombok.jar file and then click Install/Update.
Check the Eclipse installation folder to see if the lombok.jar is added.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Source code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building

Open the project folder where pom.xml is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project .
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.
After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

1. Clone mosip-config repository.

2. OpenID Bridge uses two property files, kernel-default and application-default, configure them accordingly. For instance,

OpenID bridge connects to an IAM which supports Openid and Oauth. For integration with our keycloak, Please reach out to our team.
Update mosip.iam.open-id-url property to update iam url.
Secrets can be encrypted using config server
Update Url's in property files.(It can be either pointed to any remotely or locally deployed services)

3. Download kernel-config-server.jar. For Windows, download config-server-start.bat, Linux users can run

5. To verify the config-server, hit the below URL: http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label} for instance http://localhost:51000/config/kernel/env/master

Initialization and utilization of module

Audit REST service consists of bootstrap.properties file in src/main/resources.

Below properties needed to be modified in order to connect to the config server:

spring.cloud.config.uri=<config server uri>
spring.cloud.config.label=<branch of config repo>
spring.profiles.active=default

Services can be run using Run As -> Spring Boot App/Java Application.
For API documentation, refer here.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/auditmanager/v3/api-docs/swagger-config.
The API's can be tried using postman. URLs and Body structures can be found in Swagger or curl command can be copied and imported in Postman.

ID Generator

Overview

This service is used to generate various IDs like UIN and VID.

UIN Generation Filters

The UIN should follow the following filters and constraints:

Only integers with length, as specified in mosip.kernel.uin.length configuration.
Minimum pregenerated UINs that should be available, as specified in mosip.kernel.uin.min-unused-threshold configuration. If not available then the next batch of generation would start.
Number of UINs to generate, as specified in mosip.kernel.uin.uins-to-generate configuration.
Upper bound of number of digits in sequence allowed in id, as specified in mosip.kernel.uin.length.sequence-limit configuration. For example if limit is 3, then 12 is allowed but 123 is not allowed in id (in both ascending and descending order).
Number of digits in repeating block allowed in id, as specified in mosip.kernel.uin.length.repeating-block-limit configuration. For example if limit is 2, then 4xxx4 is allowed but 48xxx48 is not allowed in id (x is any digit).
Lower bound of number of digits allowed in between two repeating digits in id, as specified in mosip.kernel.uin.length.repeating-limit configuration. For example if limit is 2, then 11 and 1x1 is not allowed in id (x is any digit).
Number of digits to check for reverse digits group limit, as specified in mosip.kernel.uin.length.reverse-digits-limit configuration. For example if limit is 5 and UIN is 4345665434, then first 5 digits will be 43456, reverse 65434.
Number of digits to check for digits group limit in id, as specified in mosip.kernel.uin.length.digits-limit configuration. For example if limit is 5 and UIN is 4345643456, then 5 digits group will be 43456.
Number of even adjacent digits limit in id, as specified in mosip.kernel.uin.length.conjugative-even-digits-limit configuration. For example, if limit is 3 then any 3 even adjacent digits is not allowed.
List of restricted numbers with , seperation as specified in mosip.kernel.uin.restricted-numbers configuration.
List of numbers that should not be the starting digits in the id. Its a , separated list, as specified in mosip.kernel.uin.not-start-with configuration. For example, the number should not contain '0' or '1' as the first digit.
No alphanumeric characters allowed.
No cyclic numbers as mentioned below are allowed. "142857", "0588235294117647", "052631578947368421", "0434782608695652173913", "0344827586206896551724137931", "0212765957446808510638297872340425531914893617", "0169491525423728813559322033898305084745762711864406779661", "016393442622950819672131147540983606557377049180327868852459", "010309278350515463917525773195876288659793814432989690721649484536082474226804123711340206185567".

Note: Significant thought has been invested in the above design to ensure the generated numbers are both random and secure. We strongly recommend retaining the stated values to maintain the integrity and security of the same.

Number of Unique IDs

The above logic reduces the space of the total number of IDs possible. As it is difficult to represent the above logic with a mathematical formula, we provide a statistical estimate of the total number of unique IDs as below:

The following code was used for this estimate.

You are encouraged to find any lacunae in this code!

Datashare

Overview

The DataShare service is used to share data with other entrusted services and partners. The mechanism shares are the following:

Retrieves and stores data to be shared in Object Store and returns a Datashare URL.
It fetches data from the Object Store when the Datashare URL is called.

The sharing of data is controlled by the Datashare policy.

Data is encrypted before sharing it with partners. Learn more about datashare encryption.

The relationship of Datashare Service with other services is explained here. NOTE: The numbers do not signify the sequence of operations or control flow. Arrows indicate the data flow.

ABIS Handler Stage creates datashare for ABIS.
Manual Adjudication Stage creates datashare for adjudication.
Verification Stage creates datashare for verification.
Datashare Service calls Policy Manager Service to get the policy for creating shares.
It calls the Keymanager Service to encrypt data as per policy.
Stores datashare inside object store.
Retrieves datashare from the object store when the datashare URL is called.
External systems like ABIS, Print System, Adjudication system etc. calls Datashare Service to get the datashare.
Print Service creates UIN PDF and uploads to datashare through Credential.
Partner Manager Service creates credentials for CA certificates to be used by ID Authentication.
Printing Stage creates credentials for printing systems and sends the data through datashare.
ID Repository Service sends data to ID Authentication system through Credential.

Keycloak

Overview

Keycloak serves as the administrative access control module in MOSIP, managing authentication and authorization across its microservices. Since MOSIP is built on a microservice architecture, it heavily relies on OAuth 2.0 tokens for access control. These tokens contain embedded role definitions that determine who can access specific microservice APIs ensuring secure and granular access control.

Keycloak's Role in MOSIP

Microservice Security – Each MOSIP microservice validates incoming API requests using OAuth 2.0 tokens issued by Keycloak. If the token lacks the necessary role, access is denied. This mechanism applies universally, even between internal MOSIP modules, ensuring a zero-trust architecture.
Data Access Control – Most sensitive data in MOSIP is encrypted in the database, making APIs the only entry point for accessing information. Keycloak enforces strict authentication and authorization policies, preventing internal attacks and API misuse.
Administrative Oversight – Administrators can monitor and control access permissions centrally via Keycloak, providing visibility into who can access what within the system.
User Repository Management – Keycloak also functions as the internal identity store for critical MOSIP roles, including:
- Operators – Handle citizen registration and data collection.
- Supervisors – Oversee registration processes and ensure compliance.
- Adjudicators – Review and resolve identity conflicts or duplicate registrations.

By enforcing strict access controls and acting as both an identity provider and an authorization enforcer Keycloak helps MOSIP maintain high security, scalability, and compliance while protecting against unauthorized access.

Persistence

Postgres DB

Overview

ER diagrams

Entity relationships diagrams for all databases used in MOSIP are given below.

Configuration parameters

Connection details
- {module_name}_database_url
- {module_name}_database_username
- {module_name}_database_password
Hibernate configurations
- javax.persistence.jdbc.driver
- hibernate.dialect
- hibernate.jdbc.lob.non_contextual_creation
- hibernate.hbm2ddl.auto
- hibernate.show_sql
- hibernate.format_sql
- hibernate.connection.charSet
- hibernate.cache.use_second_level_cache
- hibernate.cache.use_query_cache
- hibernate.cache.use_structured_entries
- hibernate.generate_statistics
- logging.level.org.hibernate.SQL
- logging.level.org.hibernate.type

Production DB configuration

These are some of the reference settings of a production database. It is expected that these are reviewed and finalized for a given deployment.

Object Store

Overview

Khazana provides following adapters to store objects

POSIX - Supports storage of packets on a filesystem. Its typically used by registration client to store packets locally on the machine. This adapter is not receommended for usage in low latency environments like packet manager.

Object Store is used for following purpose wihin mosip

Registration Client - Encrypted packets
Pre-registration - Uploaded Documents
Idrepo - Individual's biometrics and documents
Datashare - On demand individual's biometrics, documents and other information.

Note: Please note its important to choose the right partner for object storage and work with them to scale acordingly. Please follow the hardware estimate for Object Store based on respective Object store products.

The below is the list of S3 Java API's used by MOSIP. This can be used to understand the vendor compatibility. Khazana does not use any internal business logic and is purely an storage abstraction layer.

Packet Manager

Overview

Packet Manager performs the following functions:

Performs in-memory encryption and decryption of packets.
Performs security checks, checksum, file validations, ID object validations, etc. on the registration packet.

Packet Manager runs as a service and is also available as a library.

The relationship of the Packet Manager with other services is explained here.

NOTE: The numbers do not signify a sequence of operations or control flow. Arrows indicate data flow

Audit logs.
Encryption and decryption of packet.

Packet structure

API

Source code

ABIS API

This document defines the APIs specifications for various operations that ABIS can perform to integrate with MOSIP.

API specification version: 0.9

Published Date: February 05, 2021

Revision Note

Publish Date

Revision

May 07, 2020

June 09, 2020

A note related to targetFPIR was added.

June 26, 2020

New (code - 6, 8, 9, 10, 11, 12) for ABIS have been added.

August 04, 2020

Analytics section has been added to the overall response for Identify and the have been updated.

November 19, 2020

Note on encryption of biometric data share using referenceURL has been added.

February 05, 2021

Note on and was added for Insert Request.

March 23, 2021

New (code - 17) for ABIS has been added.

May 3, 2021

The logic for encryption has been updated for ABIS Datashare URL.

September 8, 2021

All possible error codes for DataShare URL has been added.

Introduction

An ABIS system that integrates with MOSIP should support the following operations.

Insert
Identify
Delete
Ping
Pending Jobs
Reference Count

All ABIS operations are via. a message queue and are asynchronous. The data sent in ABIS can be byte array or text based on a configuration in the registration processor.

Parameters

Common Parameters

Common parameters used for all ABIS operations:

Name

Description

Restrictions

Type

requestID

ID that is associated with each request sent to ABIS

ABIS should not use this ID in any other context outside the request

UUID

referenceID

ID of a single registration record. Registration record is maintained in MOSIP. This ID is the mapping between MOSIP and ABIS

None

UUID

referenceURL

URL to the biometrics data stored in MOSIP. This URL will have read only access

None

HTTPS URL

biometricType

Type of biometric data sent in the request

FID/FIR/IIR

String

returnValue

Code for response

String

failureReason

Code for failure reason

String

Standard Return Codes

Code

Status

Success

Failed

Failure Reasons

Code

Reason

internal error - Unknown

aborted

unexpected error

unable to serve the request - invalid request structure

missing referenceId (in request body)

missing requestId (in request body)

unable to fetch biometric details (using referenceURL)

missing reference URL (in request body)

missing requesttime (in request body)

referenceId already exists (in ABIS)

CBEFF has no data

referenceId not found (in ABIS)

invalid version

invalid id

invalid requesttime format

invalid CBEFF format

data share URL has expired

Biometric Quality check failed

ABIS Operations

The following operations are supported by MOSIP:

Insert
Identify
Delete
Ping
Pending Jobs
Reference Count

Insert

ABIS must get biometric data from referenceURL, process it and store it locally within the ABIS reference database. More details about the referenceURL is mentioned in our referenceURL section.
referenceId must not be active prior to this operation i.e., it must not have been used before this operation.
De-duplication must not be performed in this operation.
MOSIP will provide biometric data in CBEFF format to ABIS as a response of referenceURL and the data will be encrypted and encoded as mentioned below.

Request and Response Structure for Insert

Insert Request

{
  "id": "mosip.abis.insert",
  "version": "1.1",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "referenceURL": "https://{base_url}/v1/datashare/get/mpolicy-default-abis/mpartner-default-abis/mpartner-default-abismpolicy-default-abis20210205062412BlQo0rJB"
}

Success Response

{
  "id": "mosip.abis.insert",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Failure Response

{
  "id": "mosip.abis.insert",
  "requestId": "91234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "7"
}

Reference URL

The reference URL is MOSIP's datashare URL which is generated based on a policy defined by MOISP's adopter.

The referenceURL is authenticated and authorized; ABIS needs to send a JWT token inside the request header COOKIE.
The referenceURL will be active for a certain time as decided by the MOSIP adopter.
The data sent in the referenceURL will be encrypted.

Authentication Token

Below are the sample API details for getting the authentication token. More details about the API are available in our AuthN & AuthZ document.

Sample Request URL

POST https://{base_url}/v1/authmanager/authenticate/clientidsecretkey

Sample Request Body

{
  "id": "string",
  "metadata": {},
  "request": {
    "appId": "regproc",
    "clientId": "mosip-regproc-client",
    "secretKey": "abc123"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

Sample Response

Response Cookie:

Set-Cookie 
authorization: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJyanpjdUZPTmpBLWZRRDZYVVpYeFlldk5UZWtYcnZKVXN1RG5TeHJjZ0tZIn0.eyJqdGkiOiI2Yzg0ZDMyNi04NjZhLTRmZTQtOGJiMy02NGY0YWVjNmZiZDAiLCJleHAiOjE2MDk5NDg3NTAsIm5iZiI6MCwiaWF0IjoxNjA5OTEyNzUwLCJpc3MiOiJodHRwczovL3FhMi5tb3NpcC5uZXQva2V5Y2xvYWsvYXV0aC9yZWFsbXMvbW9zaXAiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiODdmMDU3NjQtNzg5ZC00ZTZiLTljMWUtYzU2YmJkYzI5NTYzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibW9zaXAtYWJpcy1jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiNjZjMjBiMy03OTY1LTQ0ZDUtODg3Ny00Zjk2MDNlNzI5OTEiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHBzOi8vcWEyLm1vc2lwLm5ldCJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7Im1vc2lwLWFiaXMtY2xpZW50Ijp7InJvbGVzIjpbInVtYV9wcm90ZWN0aW9uIl19LCJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJjbGllbnRJZCI6Im1vc2lwLWFiaXMtY2xpZW50IiwiY2xpZW50SG9zdCI6IjEwLjI0NC4zLjM1IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtbW9zaXAtYWJpcy1jbGllbnQiLCJjbGllbnRBZGRyZXNzIjoiMTAuMjQ0LjMuMzUifQ.ntez3ZkbDsjWi467JVj9d3kfktbUc7e6zQhHv0bVJfmiQA0N1QGyXAiZdqZrHj3cgFo0Lft54jgEtCGZZAma8nAw9IDICet9TA2A_u5hZ3oAq6HwYMS1pWb43jx5K9RRr_Yc-hdNnma754KzHhJgU1A7e_y0m88MT_oohHpRQ16jItEfC0AUQUvOAsxPwn-mmhu4uFFEq9e05ftBDIEBr24t-8feWN92uCJVMrSYHHjFL2ayg03I4Zkw1IupfLa-HACIlIToUmAk00aPxLtyWMFpOHVcLKBS2i9gEeqCEiUzklwuEp0B4aCqk5_M-Ng2X6VcGsCUJ8ACWRG4lCQQYA

{
  "id": "string",
  "version": "string",
  "responsetime": "2021-02-05T06:31:36.885Z",
  "metadata": null,
  "response": {
    "status": "Success",
    "message": "Clientid and Token combination had been validated successfully"
  },
  "errors": null
}

DataShare URL

Below is the sample API detail for reference URL.

Sample Request URL

GET https://{base_url}/v1/datashare/get/mpolicy-default-abis/mpartner-default-abis/mpartner-default-abismpolicy-default-abis20210205062412BlQo0rJB

Sample Encrypted Response

The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions

The data downloaded would be URL-safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two Parts after splitting using #KEY_SPLITTER#.

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1

#KEY_SPLITTER#

Block 2

Block 1:

Block 1, i.e. the encrypted key data is again split into three parts,

The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.
The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.
The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

Block 2, i.e. the encrypted actual data is again split into two parts,

The 1st part is the random 32 bytes which will be used as AAD in AES encryption(first 32 bytes). From this 32 bytes AAD data, the first 12 bytes is IV/Nonce.
The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

The structure of the encrypted data downloaded from referenceURL in MOSIP 1.1.5.5 or prior versions

The data downloaded would be base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two Parts after splitting using #KEY_SPLITTER#.

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1

#KEY_SPLITTER#

Block 2

Block 1:

Block 1, i.e. the encrypted key data is again split into two parts,

The first part is the Certificate Thumbprint i.e. the key identifier which is the first 32 bytes in Block 1.
The second part is the Encrypted Random AES Key which is encrypted with RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

Block 2, i.e. the encrypted actual data is again split into two parts,

The 1st part is the Encrypted data, encrypted using AES GCM PKCS5Padding.
The 2nd part is IV/Nonce i.e. the last 32 bytes appended after encrypted data.

Sample Response after Decryption

<?xml version="1.0" encoding="UTF-8"?>
<BIR xmlns="http://standards.iso.org/iso-iec/19785/-3/ed-2/">
    <BIRInfo>
        <Integrity>false</Integrity>
    </BIRInfo>
    <!-- right index finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.209Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right middle finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right ring finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right little finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left index finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left IndexFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left middle finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left MiddleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left ring finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left RingFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left little finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left LittleFinger</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right thumb finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Right Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left thumb finger -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>7</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Finger</Type>
            <Subtype>Left Thumb</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- face -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>8</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Face</Type>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- right iris -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Right</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
    <!-- left iris -->
    <BIR>
        <Version>
            <Major>1</Major>
            <Minor>1</Minor>
        </Version>
        <CBEFFVersion>
            <Major>1</Major>
            <Minor>1</Minor>
        </CBEFFVersion>
        <BIRInfo>
            <Integrity>false</Integrity>
        </BIRInfo>
        <BDBInfo>
            <Format>
                <Organization>Mosip</Organization>
                <Type>9</Type>
            </Format>
            <CreationDate>2019-06-27T13:40:06.211Z</CreationDate>
            <Type>Iris</Type>
            <Subtype>Left</Subtype>
            <Level>Raw</Level>
            <Purpose>Enroll</Purpose>
            <Quality>
                <Algorithm>
                    <Organization>HMAC</Organization>
                    <Type>SHA-256</Type>
                </Algorithm>
                <Score>100</Score>
            </Quality>
        </BDBInfo>
        <BDB>RklSAD...</BDB>
    </BIR>
</BIR>

Sample Response in case of Authentication Failure

{
  "id": null,
  "version": null,
  "responsetime": "2021-02-05T06:29:48.257Z",
  "metadata": null,
  "response": null,
  "errors": [
    {
      "errorCode": "KER-ATH-401",
      "message": "Authentication Failed"
    }
  ]
}

All Possible Error codes and Messages from Datashare URL

Error Code

Error Message

DAT-SER-003

File does not exists or File is empty

DAT-SER-006

Data share not found

DAT-SER-006

Data share usage expired

KER-ATH-401

Authentication Failed

KER-ATH-403

Forbidden

Please note that for all the functional failures MOSIP sends a response code 200.

Identify

All Insert requests added to the queue earlier must be serviced by ABIS when performing an Identify request.
Identify request provides a 1:N comparison. The given input is compared either against the gallery passed or if the gallery is not specified the entire database.
The input for comparison can be provided by referenceID or referenceURL.
- If the referenceID is given it is used as the preferred option. The given referenceID must be existing in the ABIS database else ABIS will throw an error.
- If the referenceID is omitted or NULL and the referenceURL is passed the ABIS retrieves the biometrics provided in the referenceURL and compares the same against either a gallery or its database.
- If in case, both referenceID and referenceURL are missing ABIS throws an error.

Identify requests should give to all candidates which are considered as a match based on ABIS thresholds.
This request should not match against referenceID that is not in the reference database.
The response now has a section for analytics that contains key-value pairs. Values can be JSON objects also. The contents of the analytics section will be agreed upon by the MOSIP adopter with the ABIS provider. Scores are also moved to this section and are not mandatory response parameters anymore.
Ordering or ranking of results is not explicitly specified and can be agreed upon between the MOSIP adopter and the ABIS provider.
The flags section of the request can be used to customize or control ABIS behaviour by sending specific key-value pairs.
"targetFPIR" or "maxResults" are examples of such flags that can alter ABIS behaviour. These are optional attributes for MOSIP during an identify request. MOSIP expects the adopters to define these parameters based on the accuracy expectations and workflow requirements. These can be set at the ABIS configuration level and need not be part of the individual request at all.

To give an example, please find the following calculation for targetFPIR - which is the error rate at which identification requests are expected to return a non-empty candidate list.

round (-10 * log10 (target false positive identification rate))

With this calculation:

Target False Positive Identification Rate

targetFPIR

1 in 1,000

1 in 10,000

1 in 100,000

Identify Request

{
  "id": "mosip.abis.identify",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "referenceURL": "",//will be an empty string, if not used
  "flags": { //optional
    //maxResults is an example and not a prescribed flag
	"maxResults": "10", 
	//targetFPIR is an example and not a prescribed flag
	"targetFPIR": "30",
    //there can be more following this	
	"flag1": "value1",
	"flag2": "value2" 
  },
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "2abe7b7d-b58a-4466-a006-c79297281123"
      }, 
      {
        "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456"
      }, 
      {
        "referenceId": "3bce7b7d-b58a-4466-a006-c79297281678"
      }, 
      {
        "referenceId": "5cce7b7d-b58a-4466-a006-c79297281098"
      }, 
      {
        "referenceId": "2cce7b7d-b58a-4466-a006-c79297281321"
      } 
    ]
  }
}

Success Response

{
  "id": "mosip.abis.identify",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456",
        "analytics": {
		  //internalScore is an example and not prescribed
		  "internalScore": "112", 
		  //confidence is an example and not prescribed
          "confidence": "90",
		  //there can be more following this	
		  "key1": "value1",
		  "key2": "value2"
        },
		// modality wise analytics
        "modalities": [ 
          {
            "biometricType": "FIR",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          },
		  {
            "biometricType": "IIR",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          },
		  {
            "biometricType": "FID",
            "analytics": {
			  "confidence": "90",
              "internalScore": "112",
			  "key1": "value1",
			  "key2": "value2"
            }
          }
        ]
      }
    ]
    "analytics": {
      //This is an optional section
      //Data in this section can be agreed upon between the MOSIP adopter and the ABIS Provider
	}
  }
}

Failure Response

{
  "id": "mosip.id.identify",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "7"
}

Delete

Removes only the entry referred by the referenceId.
This operation can be used to remove duplicates found by Identify.

Delete Request

{
  "id": "mosip.abis.delete",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
  "referenceId": "7acce7b7d-b58a-4466-a006-c79297281456"
}

Success response

{
  "id": "mosip.abis.delete",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Failure response

{
  "id": "mosip.abis.delete",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "2",
  "failureReason": "1"
}

Ping

A Ping request should respond with a response on the liveness of the ABIS system.

Ping Request

{
  "id": "mosip.abis.ping",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success response

{
  "id": "mosip.abis.ping",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "returnValue": "1"
}

Pending Jobs

ABIS responds with the count of requests that are still pending.

Pending Jobs Request

{
  "id": "mosip.abis.pendingJobs",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success Response

{
  "id": "mosip.abis.pendingJobs",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "jobscount": "10",
  "returnValue": "1"
}

Reference Count

ABIS will send a count of records in the reference database

Reference Count Request

{
  "id": "mosip.abis.referenceCount",
  "version": "1.1",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2020-03-29T07:01:24.692Z",
}

Success Response

{
  "id": "mosip.abis.referenceCount",
  "requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2020-03-29T07:01:24.692Z",
  "count": "10",
  "returnValue": "1"
}

References

Biometric Specification to know about the biometric specification in MOSIP.
CBEFF XML to know how MOSIP stores biometric data.
Authentication and Authorization API to get the JWT token.
MOSIP's de-duplication process for details about the De-Duplication process in MOSIP.

MDS Specification

Introduction & Background

Objective

The objective of this specification document is to establish the technical and compliance standards/ protocols that are necessary for a biometric device to be used in MOSIP solutions.

Target Audience

MOSIP Devices

All devices that collect biometric data for MOSIP should operate within the specification of this document.

Revision History

Version

State

Date

Changes

0.9.2

Frozen

Aug-2019

0.9.3

Frozen

Feb-2020

0.9.5

Draft

13-Jun-2020

0.9.5

Draft

10-Aug-2020

Signature for API to retrieve encryption certificate has been changed from GET to POST and Device Stream now supports an optional parameter - timeout

0.9.5

Draft

04-Dec-2020

In the header of JWT Signature, the key to store the type has been changed to "typ" from "type" as per JWT standards. Kindly view the digital id specification for the change.

0.9.5

Draft

26-Feb-2021

Updated the to include PCI PED 2.0 and CC.

0.9.5

Draft

24-Mar-2021

The reference to L2 devices has been removed from this document. The biometric specification listed here has been moved to a new section and the old specification is now in for reference.

0.9.5

Draft

07-Apr-2021

Device De registration API spec was updated.

0.9.5

Draft

08-Apr-2021

We will be following datetime values in ISO 8601 with format yyyy-mm-ddTHH:MM:ssZ. The same has been updated throughout the document.

0.9.5

Draft

24-May-2021

Clarification on hash and previousHash definition has been provided

0.9.5

Draft

04-Apr-2022

0.9.5

Draft

27-Jul-2022

Added the section on

0.9.5

Draft

24-Oct-2023

Added error code for devices in busy or not ready state. Also added validation for transactionID in request parameters.

Glossary of Terms

Device Provider - An entity that manufactures or imports the devices in their name. This entity should have legal rights to obtain an organization-level digital certificate from the respective authority in the country.
FTM Provider - An entity that manufactures or guarantees the trustworthiness of the foundational trust module. This can be the device provider as well.
Device - A hardware capable of capturing biometric information.
L1 Certified Device / L1 Device - A device certified as capable of performing encryption in line with this spec in its trusted zone.
L0 Certified Device / L0 Device - A device certified as one where the encryption is done on the host machine device driver or the MOSIP device service.
FTM Provider Certificate - A digital certificate issued to the "Foundational Trust Provider". This certificate proves that the provider has successfully gone through the required Foundational Trust Provider evaluation. The entity is expected to keep this certificate in secure possession in an HSM. All the individual FTM trust certificates are issued using this certificate as the root. This certificate would be issued by the countries in conjunction with MOSIP.
Device Provider Certificate - A digital certificate issued to the "Device Provider". This certificate proves that the provider has been certified for L0/L1 respective compliance. The entity is expected to keep this certificate in secure possession in an HSM. All the individual trust certificates are issued using this certificate as the root. This certificate is issued by the countries in conjunction with MOSIP.
Registration - The process of applying for a Foundational Id.
KYC - Know Your Customer. The process of providing consent to perform profile verification and update.
Auth - The process of verifying one’s identity.
FPS - Frames Per Second
Management Server - A server run by the device provider to manage the life cycle of the biometric devices.
Device Registration - The process of a device obtaining a certificate from the management server.
Signature - All signatures should be as per RFC 7515.
header in signature - The header in the signature means the attribute with "alg" set to RS256 and x5c set to base64encoded certificate.
payload is the byte array of the actual data, always represented as base64urlencoded.
signature - base64urlencoded signature bytes
ISO format timestamp | ISO 8601 with the format yyyy-mm-ddTHH:MM:ssZ (Example: 2020-12-08T09:39:37Z). This value should be in UTC (Coordinated Universal Time).

Device Specification

Device Capability

The MOSIP-compliant device is expected to perform the following,

Should have the ability to collect one or more biometric
Should have the ability to sign the captured biometric image or template.
Should have the ability to protect secret keys
Should have no mechanism to inject the biometric

Base Specifications for Devices

For details about biometric data specifications please view the page MOSIP Biometric Specification.

We recommend that countries look at ergonomics, accessibility, ease of usage, and common availability of devices while choosing devices for use in registration and authentication scenarios.

Device Trust

L1 - The trust is provided by a secure chip with a secure execution environment.
L0 - The trust is provided at the software level. No hardware-related trust exists. This type of compliance is used in controlled environments.

Foundational Trust Module (FTM)

The module can securely generate, store and process cryptographic keys.
Generation of asymmetric keys and symmetric keys with TRNG.
The module can protect keys from extraction.
The module has to protect the keys from physical tampering, temperature, frequency and voltage-related attacks.
The module could withstand Hardware cloning.
The module could withstand probing attacks
The module provides memory segregation for cryptographic operations and protection against buffer overflow attacks
The module provides the ability to withstand cryptographic side-channel attacks like Differential Power analysis attacks, Timing attacks.
CAVP validated the implementation of the cryptographic algorithm.
The module can perform a cryptographically validatable secure boot.
The module can run trusted applications.

Secure Boot
- Ability to cryptographically verify code before execution.
- Ability to check for integrity violations of the module/device.
- Halt upon failure.
- Ability to securely upgrade and perform forward-only upgrades, to thwart downgrade attacks.
- SHA256 hash equivalent or above should be used for all hashing requirements
- All root of trust is provisioned upon first boot or before.
- All upgrades would be considered a success only after the successful boot with proper hash and signature verification.
- The boot should fail upon hash/signature failures and would never operate in an intermediary state.
- A maximum of 10 failed attempts should lock the upgrade process and brick the device. However, chip manufacturers can decide to be less than 10.
Secure application
- Ability to run applications that are trusted.
- Protect against the downgrading of applications.
- Isolated memory to support cryptographic operations.
- All trust is anchored during the first boot and not modifiable.

Certification

The FTM should have at least one of the following certifications in each category to meet the given requirement.

Category: Cryptographic Algorithm Implementation

CAVP (RSA, AES, SHA256, TRNG (DRBGVS), ECC)

{% hint style="info" %} The supported algorithm and curves are listed here {% endhint %}

Category: FTM Chip

(ONE of the following certifications)

FIPS 140-2 L3 or above
PCI PTS 5 or above (Pre-certified)
PCI - PED 2.0 or above (Pre-Certified)
One of the following Common Criteria (CC) certification
- https://www.commoncriteriaportal.org/files/ppfiles/pp0035a.pdf
- https://www.commoncriteriaportal.org/files/ppfiles/pp0084a_pdf.pdf

System/Device Level Tamper (optional)

Threats to Protect

The FTM should protect against the following threats.

Hardware cloning attacks - Ability to protect against attacks that could result in a duplicate with keys.
Hardware Tamper attacks
- Physical tamper - No way to physically tamper and obtain its secrets.
- Voltage & frequency related attacks - Should shield against voltage leaks and should prevent low voltage. The FTM should always be in either the state operational normally or inoperable. The FTM should never be operable when its input voltages are not met.
- Temperature attacks on the crypto block - Low or High the FTM are expected to operate or reach an inoperable state. No state in between.
Differential Power Analysis attack.
Probing attacks - FTM should protect its surface area against any probe-related attacks.
Segregation of memory for execution of cryptographic operation (crypto block should be protected from buffer overflow type attacks).
Vulnerability of the cryptographic algorithm implementation.
Attacks against secure boot & secure upgrade.
TEE/Secure processor OS attack (if applicable).

Foundational Trust Module Identity

{% hint style="info" %} The validity of the chip certificate can not exceed 20 years from the date of manufacturing. {% endhint %}

Device

L0 - A device can obtain L0 certification when it uses a software-level cryptographic library with no secure boot or FTM. These devices will follow different device identities and the same would be mentioned as part of exception flows.
L1 - A device can obtain L1 certification when it is built in a secure facility with one of the certified FTM.

Device Identity

All devices that connect to MOSIP must be identifiable. MOSIP believes in cryptographic Identity as its basis for trust.

Physical ID

Digital ID

A digital device ID in MOSIP would be a signed JSON (RFC 7515) as follows:

{
  "serialNo": "Serial number",
  "make": "Make of the device",
  "model": "Model of the device",
  "type": "Type of the biometric device",
  "deviceSubType": "Subtypes of the biometric device",
  "deviceProvider": "Device provider name",
  "deviceProviderId": "Device provider id",
  "dateTime": "Current datetime in ISO format"
}

The only exception to this rule is for the L0-compliant devices that have the purpose of "Registration". L0 devices would sign the Digital Id with the device key.

A signed digital ID would look as follows:

"digitalId": "base64urlencoded(header).base64urlencoded(payload).base64urlencoded(signature)"

The header in the digital id would have:

"alg": "RS256",
"typ": "JWT",
"x5c": "<Certificate of the FTM chip, If in case the chain of certificates are sent then the same will be ignored">

MOSIP assumes that the first certificate in the x5c is the FTM's chip public certificate issued by the FTM root certificate.

An unsigned digital ID would look as follows:

"digitalId": "base64urlencoded(payload)"

Payload is the Digital ID JSON object.

Accepted Values for Digital ID

Parameters

Description

serialNo

Serial number of the device.
This value should be same as printed on the device (Refer ).

make

Brand name.
This value should be the same as printed on the device (Refer to ).

model

Model of the device.
This value should be the same as printed on the device (Refer to ).

type

Currently allowed values for device type are "Finger", "Iris" or "Face".
More types can be added based on Adopter's implementation.

deviceSubType

The device subtype is based on the device type.
For Finger - "Slap", "Single" or "Touchless"
For Iris - "Single" or "Double"
For Face - "Full face"

deviceProvider

Name of the device provider.
The device provider should be a legal entity in the country.

dateTime

The current time during the issuance of the request.
This is in ISO format.

Keys

List of keys used in the device and their explanation.

Device Key

FTM Key

MOSIP Key

The MOSIP key is the public key provided by the MOSIP adopter. This key is used to encrypt the biometric. Details of the encryption are listed below. We recommend rotating this key every 1 year.

Device Service - Communication Interfaces

The section explains the necessary details of the biometric device connectivity, accessibility, discover-ability and protocols used to build and communicate with the device.

Device Discovery

Device Discovery Request

{
  "type": "type of the device"
}

Accepted Values for Device Discovery Request

type - "Biometric Device", "Finger", "Face", "Iris"

{% hint style="info" %} "Biometric Device" - is a special type and is used in case you are looking for any biometric device. {% endhint %}

Device Discovery Response

[
  {
    "deviceId": "Internal ID",
    "deviceStatus": "Device status",
    "certification": "Certification level",
    "serviceVersion": "Device service version",
    "deviceSubId": ["Array of supported device sub Ids"],
    "callbackId": "Base URL to reach the device",
    "digitalId": "Unsigned Digital ID of the device",
    "deviceCode": "Same as serialNo in digital ID",
    "specVersion": ["Array of supported MDS specification version"],
    "purpose": "Auth or Registration or empty if not registered",
    "error": {
      "errorCode": "101",
      "errorInfo": "Invalid JSON Value Type For Discovery.."
    }
  },
  ...
]

Accepted Values for Device Discovery Response

Parameters

Description

deviceStatus

Allowed values are "Ready", "Busy", "Not Ready" or "Not Registered".
Error codes should be sent for device in "Busy", "Not Ready" and "Not Registered" from the below .

certification

Allowed values are "L0" or "L1" based on the level of certification.

serviceVersion

Device service version.

deviceId

Internal ID to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

callbackId

This differs as per the OS.
In the case of Linux and windows operating systems, it is an HTTP URL.
In the case of android, it is the intent name.
In IOS, it is the URL scheme.
The call-back URL takes precedence over future requests as a base URL.

digitalId

Digital ID as per the Digital ID definition but it will not be signed.

deviceCode

Same as serialNo in digital ID.

specVersion

An array of supported MDS specification versions. The array element zero will always contain the spec version using which the response is created.

purpose

Purpose of the device in the MOSIP ecosystem. Allowed values are "Auth" or "Registration".

error

Relevant errors as defined under the of this document.

error.errorCode

A standardized error code is defined in the .

error.errorInfo

Description of the error that can be displayed to the end user. Multi-lingual support.

{% hint style="info" %}

The response is an array that we could have a single device enumerating with multiple biometric options.
The service should ensure to respond only if the type parameter matches the type of device or the type parameter is a "Biometric Device".
This response is a direct JSON as shown in the response. {% endhint %}

Windows/Linux

HTTP Request:

MOSIPDISC http://127.0.0.1:<device_service_port>/device
HOST: 127.0.0.1: <device_service_port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:http://127.0.0.1:<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %}

The payloads are JSON in both cases and are part of the body.
CallbackId would be set to the http://127.0.0.1:<device_service_port>/. So, the caller will use the respective HTTP verb/method and the URL to call the service. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Device Info

The device information API would be used to identify the MOSIP-compliant devices and their status by the applications.

Device Info Request

Accepted Values for Device Info Request

Device Info Response

[
  {
    "deviceInfo": {
      "deviceStatus": "Current status",
      "deviceId": "Internal ID",
      "firmware": "Firmware version",
      "certification": "Certification level",
      "serviceVersion": "Device service version",
      "deviceSubId": ["Array of supported device sub Ids"],
      "callbackId": "Baseurl to reach the device",
      "digitalId": "Signed digital id as described in the digital id section of this document.",
      "deviceCode": "Same as serialNo in digital ID",
      "env": "Target environment",
      "purpose": "Auth or Registration",
      "specVersion": ["Array of supported MDS specification version"],
    },
    "error": {
      "errorCode": "101",
      "errorInfo": "Invalid JSON Value "
    }
  }
  ...
]

So the API would respond in the following format.

[
  {
    "deviceInfo": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
    "error": {
      "errorCode": "100",
      "errorInfo": "Device not registered. In this case, the device info will be only base64urlencode(payload)"
    }
  }
]

Allowed values for Device Info Response

Parameters

Description

deviceInfo

The deviceInfo object is sent as JSON Web Token (JWT).
For a device which is not registered, the deviceInfo will be unsigned.
For a device which is registered, the deviceInfo will be signed using the device key.

deviceInfo.deviceStatus

This is the status of the device.
Allowed values are "Ready", "Busy", "Not Ready" or "Not Registered".
Error codes should be sent for device in "Busy", "Not Ready" and "Not Registered" from the below .

deviceInfo.deviceId

Internal Id to identify the actual biometric device within the device service.

deviceInfo.firmware

The exact version of the firmware.
In the case of L0, this is the same as serviceVersion.

deviceInfo.certification

Allowed values are "L0" or "L1" based on the level of certification.

deviceInfo.serviceVersion

The version of the MDS specification that is supported.

deviceInfo.deviceId

Internal ID to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

deviceInfo.callbackId

This differs as per the OS.
In the case of Linux and windows operating systems, it is an HTTP URL.
In the case of android, it is the intent name.
In IOS, it is the URL scheme.
The call-back URL takes precedence over future requests as a base URL.

deviceInfo.digitalId

The digital id is as per the digital id definition.
For L0 devices which is not registered, the digital id will be unsigned.
For L0 devices which are registered, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

deviceInfo.env

The target environment.
For devices that are not registered the environment is "None".
For a device that is registered, then send the environment in which it is registered.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

deviceInfo.purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

deviceInfo.specVersion

An array of supported MDS specification versions. The array element Zero will always contain the spec version using which the response is created.

error

Relevant errors as defined under the of this document.

error.errorCode

A standardized error code is defined in the .

error.errorInfo

Description of the error that can be displayed to the end user. Multi-lingual support.

{% hint style="info" %}

The response is an array that we could have a single device enumerating with multiple biometric options.
The service should ensure to respond only if the type parameter matches the type of device or the type parameter is a "Biometric Device". {% endhint %}

Windows/Linux

HTTP Request:

MOSIPDINFO http://127.0.0.1:<device_service_port>/info
HOST: 127.0.0.1:<device_service_port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:http://127.0.0.1:<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %} The payloads are JSON in both cases and are part of the body. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Capture

Capture Request

{
  "env": "Target environment",
  "purpose": "Auth or Registration",
  "specVersion": "Expected version of the MDS spec",
  "timeout": "Timeout for capture",
  "captureTime": "Capture request time in ISO format",
  "domainUri": "URI of the auth server",
  "transactionId": "Transaction Id for the current capture",
  "bio": [
    {
      "type": "Type of the biometric data",
      "count":  "Finger/Iris count, in case of face max, is set to 1",
      "bioSubType": ["Array of subtypes"],
      "requestedScore": "Expected quality score that should match to complete a successful capture",
      "deviceId": "Internal Id",
      "deviceSubId": "Specific Device Sub Id",
      "previousHash": "Hash of the previous block"
    }
  ],
  "customOpts": {
    //Max of 50 key-value pairs. This is so that vendor-specific parameters can be sent if necessary. The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications. Vendors are free to include additional parameters and fine-tuning parameters. None of these values should go undocumented by the vendor. No sensitive data should be available in the customOpts.
  }
}

{% hint style="info" %} The count value should be driven by the count of the bioSubType for Iris and Finger. For Face, there will be no bioSubType but the count should be "1". {% endhint %}

Allowed Values for Capture Request

Parameters

Description

env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

specVersion

Expected version of MDS specification.

timeout

Max time the app will wait for the capture.
It's expected that the API will respond back before the timeout with the best frame.
All timeouts are in milliseconds.

captureTime

Time of capture in ISO format.
The time is as per the requested application.

domainUri

URI of the authentication server.
This can be used to federate across multiple providers or countries or unions.

transactionId

Unique Id of the transaction.
This is an internal Id to the application that's requesting a capture.
Different IDs should be used for every request.
The transactionId can have minimum lenght as 4 and max length as 50.
Allowed characters in transactionId are alphabets, numbers and hyphens (-).
If the above validations are not met then a error can be thrown in the .

bio.type

Allowed values are "Finger", "Iris" or "Face".

bio.count

The number of biometric data that is collected for a given type.
The device should validate and ensure that this number is in line with the type of biometric that's captured.

bio.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

bio.requestedScore

bio.deviceId

Internal Id to identify the actual biometric device within the device service.

bio.deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific model of the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index that always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

bio.previousHash

customOpts

In case, the device vendor wants to send additional parameters they can use this to send key-value pairs if necessary.
The values cannot be hard coded and have to be configured by the app's server and should be modifiable upon need by the applications.
Vendors are free to include additional parameters and fine-tune the process.
None of these values should go undocumented by the vendor.
No sensitive data should be available in the customOpts.

NFIQ v1.0 on a scale of 0-100 (quality score).

Scale

NFIQ v1.0

81 - 100

61 - 80

41 - 60

21 - 40

0 - 20

Capture Response

{
  "biometrics": [
    {
      "specVersion": "MDS spec version",
      "data": {
        "digitalId": "digital Id as described in this document",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioType": "Finger",
        "bioSubType": "UNKNOWN",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "domainUri": "URI of the auth server",
        "bioValue": "Encrypt biodata (ISO) with random 256-bit AES key (session key) and encode encrypted biodata with base64 URL safe encoding.",
        "transactionId": "Unique transaction id",
        "timestamp": "Capture datetime in ISO format",
        "requestedScore": "Floating point number to represent the minimum required score for the capture",
        "qualityScore": "Floating point number representing the score for the current capture"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
      "sessionKey": "Encrypt the session key (used to encrypt the bioValue) with MOSIP public key and encode encrypted session key with base64 URL safe encoding.",
      "thumbprint": "SHA256 representation of the certificate (HEX encoded) that was used for encryption of session key. All texts to be treated as uppercase without any spaces or hyphens.",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value"
      }
    },
    {
      "specVersion": "MDS spec version",
      "data": {
        "digitalId": "Digital Id as described in this document",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioType": "Finger",
        "bioSubType": "Left IndexFinger",
        "purpose": "Auth or Registration",
        "env": "target environment",
        "domainUri": "URI of the auth server",
        "bioValue": "Encrypt biodata (ISO) with random 256-bit AES key (session key) and encode encrypted biodata with base64 URL safe encoding.",
        "transactionId": "unique transaction id",
        "timestamp": "Capture datetime in ISO format",
        "requestedScore": "Floating point number to represent the minimum required score for the capture",
        "qualityScore": "Floating point number representing the score for the current capture"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
      "sessionKey": "Encrypt the session key (used to encrypt the biovalue) with MOSIP public key and encode encrypted session key with base64 URL safe encoding.",
      "thumbprint": "SHA256 representation of the certificate (HEX encoded) that was used for encryption of session key. All texts to be treated as uppercase without any spaces or hyphens.",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value"
      }
    }
  ]
}

Accepted Values for Capture Response

Parameters

Description

specVersion

The version of the MDS specification using which the response was generated.

data

The data object is sent as JSON Web Token (JWT).
The data block will be signed using the device key.

data.digitalId

The digital id is as per the digital id definition in JWT format.
For L0 devices, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

data.deviceCode

Same as serialNo in digital ID.

data.deviceServiceVersion

MDS version

data.bioType

Allowed values are "Finger", "Iris" or "Face".

data.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

data.purpose

The purpose of the device in the MOSIP ecosystem.
Allowed values are "Auth".

data.env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

data.domainUri

URI of the authentication server.
This can be used to federate across multiple providers or countries or unions.

data.bioValue

data.transactionId

Same transactionId shared in the request should be used.

data.timestamp

Time as per the biometric device.

Note: The biometric device is expected to sync its time from the management server at regular intervals so accurate time could be maintained on the device.

data.requestedScore

Floating point number to represent the minimum required score for the capture. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned above.

data.qualityScore

The floating point number represents the score for the current capture. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned above.

hash

sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)

sessionKey

thumbprint

SHA256 representation of the certificate (HEX encoded) that was used for encryption of the session key. All texts are to be treated as uppercase without any spaces or hyphens.

error

Relevant errors as defined under the of this document.

error.errorCode

Standardized error code defined in the .

error.errorInfo

Description of the error that can be displayed to the end-user. Multi-lingual support.

The entire data object is sent in JWT format. So, the data object will look like this:

"data" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)
payload - is defined as the entire byte array of the data block.

Windows/Linux

The applications that require capturing biometric data from a MOSIP device could do so by sending the HTTP request to the supported port range.

HTTP Request:

CAPTURE [http://127.0.0.1:<device_service_port>/capture](http://127.0.0.1/capture)
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response:

HTTP/1.1 200 OK
CACHE-CONTROL:no-store
LOCATION:[http://127.0.0.1](http://127.0.0.1):<device_service_port>
Content-Length: length in bytes of the body
Content-Type: application/json
Connection: Closed

{% hint style="info" %} The payloads are JSON in both cases and are part of the body. {% endhint %}

Android

For details on android specifications please view the section - Android SBI Specification.

Device Stream

Used only for registration module-compatible devices. This API is visible only for the devices that are registered for the purpose of "Registration".

Device Stream Request

{
  "deviceId": "Internal Id",
  "deviceSubId": "Specific device sub Id",
  "timeout": "Timeout for stream"
}

Allowed Values for device Stream Request

Parameters

Description

deviceId

Internal Id to identify the actual biometric device within the device service.

deviceSubId

Allowed values are 1, 2 or 3.
The device sub-id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index which always starts with 1 and increases sequentially for each sub-device present.
In the case of Finger/Iris, it's 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

timeout

Max time after which the stream should close.
This is an optional parameter and by default, the value will be 5 minutes.
All timeouts are in milliseconds.

Device Stream Response

Live Video stream with a quality of 3 frames per second or more using M-JPEG.

Error Response for Device Stream

{
  "error": {
    "errorCode": "202",
    "errorInfo": "No Device Connected."
  }
}

Windows/Linux

The applications that require more details of the MOSIP devices could get them by sending the HTTP request to the supported port range.

HTTP Request:

STREAM   http://127.0.0.1:<device_service_port>/stream
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response: HTTP Chunk of frames to be displayed. Minimum frames 3 per second.

Android

For details on android specifications please view the section - Android SBI Specification.

Registration Capture

The API is used by devices that are compatible with the registration module. This API should not be supported by devices that are compatible with authentication.

Registration Capture Request

{
  "env":  "Target environment",
  "purpose": "Auth or Registration",
  "specVersion": "Expected MDS spec version",
  "timeout": "Timeout for registration capture",
  "captureTime": "Time of capture request in ISO format",
  "transactionId": "Transaction Id for the current capture",
  "bio": [
    {
      "type": "Type of the biometric data",
      "count":  "Finger/Iris count, in case of face max, is set to 1",
      "bioSubType": ["Array of subtypes"], //Optional
      "exception": ["Finger or Iris to be excluded"],
      "requestedScore": "Expected quality score that should match to complete a successful capture",
      "deviceId": "Internal Id",
      "deviceSubId": "Specific device Id",
      "previousHash": "Hash of the previous block"
    }
  ],
  "customOpts": {
    //max of 50 key-value pairs. This is so that vendor-specific parameters can be sent if necessary. The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications. Vendors are free to include additional parameters and fine-tuning parameters. None of these values should go undocumented by the vendor. No sensitive data should be available in the customOpts.
  }
}

Accepted Values for Registration Capture Request

Parameters

Description

env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

purpose

The purpose of the device in the MOSIP ecosystem.
For devices that are not registered the purpose is empty.
Allowed values are "Auth" or "Registration".

specVersion

Expected version of MDS specification.

timeout

Max time the app will wait for the capture.
Its expected that the API will respond back before timeout with the best frame.
All timeouts are in milliseconds.

captureTime

Time of capture in ISO format.
The time is as per the requesting application.

transactionId

Unique Id of the transaction.
This is an internal Id to the application that's requesting a capture.
Different IDs should be used for every request.
The transactionId can have minimum lenght as 4 and max length as 50.
Allowed characters in transactionId are alphabets, numbers and hyphens (-).
If the above validations are not met then a error can be thrown in the .

bio.type

Allowed values are "Finger", "Iris" or "Face".

bio.count

Number of biometric data that is collected for a given type.
The device should validate and ensure that this number is in line with the type of biometric that's captured.

bio.bioSubType

Array of bioSubType for respective biometric type.
For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType
This is an optional parameter.

bio.exception

This is an array and all the exceptions are marked.
In case exceptions are sent for face then follow the exception photo specification above.
For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb"]
For Iris: ["Left", "Right"]

bio.requestedScore

Upon reaching the quality score the biometric device is expected to auto capture the image.

bio.deviceId

Internal Id to identify the actual biometric device within the device service.

bio.deviceSubId

Allowed values are 1, 2 or 3.
The device sub id could be used to enable a specific module in the scanner appropriate for a biometric capture requirement.
Device sub id is a simple index that always starts with 1 and increases sequentially for each sub-device present.
In case of Finger/Iris its 1 for left slap/iris, 2 for right slap/iris and 3 for two thumbs/irises.
The device sub id should be set to 0 if we don't know any specific device sub id (0 is not applicable for fingerprint slap).

bio.previousHash

customOpts

In case, the device vendor wants to send additional parameters they can use this to send key value pair if necessary.
The values cannot be hard coded and have to be configured by the apps server and should be modifiable upon need by the applications.
Vendors are free to include additional parameters and fine-tuning the process.
None of these values should go undocumented by the vendor.
No sensitive data should be available in the customOpts.

Registration Capture Response

{
  "biometrics": [
    {
      "specVersion": "MDS Spec version",
      "data": {
        "digitalId": "Digital id of the device as per the Digital Id definition..",
        "bioType": "Biometric type",
        "deviceCode": "Same as serialNo in digital ID",
        "deviceServiceVersion": "MDS version",
        "bioSubType": "Left IndexFinger",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "bioValue": "base64urlencoded biometrics (ISO format)",
        "transactionId": "Unique transaction id sent in request",
        "timestamp": "2019-02-15T10:01:57Z",
        "requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100.",
        "qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100."
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",    
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' } "
      }
    },
    {
      "specVersion": "MDS Spec version",
      "data": {
        "deviceCode": "Same as serialNo in digital ID",
        "bioType": "Finger",
        "digitalId": "Digital id of the device as per the Digital Id definition.",
        "deviceServiceVersion": "MDS version",
        "bioSubType": "Left MiddleFinger",
        "purpose": "Auth or Registration",
        "env": "Target environment",
        "bioValue": "base64urlencoded extracted biometric (ISO format)",
        "transactionId": "Unique transaction id sent in request",
        "timestamp": "2019-02-15T10:01:57Z",
        "requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100",
        "qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100"
      },
      "hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",
      "error": {
        "errorCode": "101",
        "errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' }"
      }
    }
  ]
}

Allowed Values for Registration Capture Response

Parameters

Description

specVersion

Version of the MDS specification using which the response was generated.

data

The data object is sent as JSON Web Token (JWT).
The data block will be signed using the device key.

data.bioType

Allowed values are "Finger", "Iris" or "Face".

data.digitalId

The digital id as per the digital id definition in JWT format.
For L0 devices, the digital id will be signed using the device key.
For L1 devices, the digital id will be signed using the FTM key.

data.bioSubType

For Finger: ["Left IndexFinger", "Left MiddleFinger", "Left RingFinger", "Left LittleFinger", "Left Thumb", "Right IndexFinger", "Right MiddleFinger", "Right RingFinger", "Right LittleFinger", "Right Thumb", "UNKNOWN"]
For Iris: ["Left", "Right", "UNKNOWN"]
For Face: No bioSubType

data.deviceServiceVersion

MDS Version

data.env

The target environment.
Allowed values are "Staging", "Developer", "Pre-Production" or "Production".

data.purpose

The purpose of the device in the MOSIP ecosystem.
Allowed values are "Auth" or "Registration".

data.bioValue

Base64-URL-encoded biometrics (in ISO format)

data.transactionId

Same transactionId shared in the request should be used.

data.timestamp

Time as per the biometric device.

Note: The biometric device is expected to sync its time from the management server at regular intervals so accurate time could be maintained on the device.

data.requestedScore

Floating point number to represent the minimum required score for the capture.

data.qualityScore

Floating point number representing the score for the current capture.

hash

sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data).

error

Relevant errors as defined under the of this document.

error.errorCode

Standardized error code defined in the .

error.errorInfo

Description of the error that can be displayed to end user. Multi lingual support.

Windows/Linux

The applications that require more details of the MOSIP devices could get them by sending the HTTP request to the supported port range.

HTTP Request:

RCAPTURE  http://127.0.0.1:<device_service_port>/capture
HOST: 127.0.0.1: <apps port>
EXT: <app name>

HTTP Response: HTTP response.

Android

For details on android specifications please view the section - Android SBI Specification.

Certificates

The MOSIP server would provide the following retrieve encryption certificate API which is white-listed to the management servers of the device provider or their partners.

Retrieve Encryption Certificate Request URL

POST https://{base_url}/v1/masterdata/device/encryptioncertficates

Version: v1

Retrieve Encryption Certificate Request

{
  "id": "io.mosip.auth.country.certificate",
  "version": "certificate server API version as defined above",
  "request": {
    "data": {
      "env":  "target environment",
      "domainUri": "uri of the auth server"
    }
  },
  "requesttime": "current timestamp in ISO format"
}

The request is sent in a JWT format. So the final request will look like this:

"request": {
  "data": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
}

Accepted Values for Retrieve Certificate Request

env - Allowed values are Staging| Developer| Pre-Production | Production
domainUri - unique uri per auth providers. This can be used to federate across multiple providers or countries or unions.

Encryption Certificate Response

{
  "id": "io.mosip.auth.country.certificate",
  "version": "certificate server API version as defined above",
  "responsetime": "Current time in ISO format",
  "response": [
    {
      "certificate": "base64encoded certificate as x509 V3 format"
    }
  ]
}

The entire response is sent in a JWT format. So the final response will look like this:

"response" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"

Management Server and Management Client

Management Server Functionalities and Interactions

The management server has the following objectives.

Validate the devices to ensure they genuine devices from the respective device provider. This can be achieved using the device info and the certificates for the Foundational Trust Module.
Register the genuine device with the MOSIP device server.
Manage/Sync time between the end device and the server. The time to be synced should be the only trusted time accepted by the device.
Ability to issue commands to the end device for
1. De-registration of the device (Device Keys)
2. Collect device information to maintain, manage, support and upgrade a device remotely.
A central repository of all the approved devices from the device provider.
Safe storage of keys using HSM FIPS 140-2 Level 3. These keys are used to issue the device certificate upon registration. The Management Server is created and hosted by the device provider outside of MOSIP software. The communication protocols between the MDS and the Management Server can be decided by the respective device provider. Such communication should be restricted to the above-specified interactions only. No transactional information should be sent to this server.
Should have the ability to push updates from the server to the client devices.

Management Client

For better and more efficient handling of the device at large volumes, we expect the devices to auto-register to the Management Server.
All communication to the server and from the server should follow the below properties.
1. All communication is digitally signed with the approved algorithms
2. All communication to the server is encrypted using one of the approved public key cryptography (HTTPS – TLS1.2/1.3 is required with one of the approved algorithms.
3. All request has timestamps attached in ISO format to the milliseconds inside the signature.
4. All communication back and forth should have the signed digital id as one of the attributes.
It's expected that auto-registration has an absolute way to identify and validate the devices.
The management client should be able to detect the devices in a plug-and-play model.
All key rotations should be triggered from the server.
Should have the ability to detect if it's speaking to the right management server.
All upgrades should be verifiable and the client should have the ability to verify software upgrades.
Should not allow any downgrade of software.
Should not expose any API to capture biometrics. The management server should have no ability to trigger a capture request.
No logging of biometric data is allowed. (Both in the encrypted and unencrypted format)

Compliance

Secure Provisioning

Secure provisioning applies to both the FTM and the Device providers.

The devices and FTM should have a mechanism to protect against fraudulent attempts to create or replicate.
The device and FTM trust should be programmed in a secure facility that is certified by the respective MOSIP adopters.
The organization should have a mechanism to segregate the FTMs and Devices built for MOSIP using a cryptographically valid and repeatable process.
All debug options within the FTM or device should be disabled permanently
All key creations need for provisioning should happen automatically using FIPS 140-2 Level 3 or higher devices. No individual or group or organization should have a mechanism to influence this behaviour.
Before the devices/FTM leaves the secure provisioning facility all the necessary trust should be established and should not be re-programmable.

{% hint style="info" %}

As there is no adopter-specific information being exchanged at the management server or the FTM provisioning server, there are no mandates from MOSIP where these are located globally. However, the adopter is recommended to have an audit and contractual mechanisms to validate the compliance of these components at any point in time.* {% endhint %}

Compliance Level

API

Compatible

Device Discovery

L0/L1

Device Info

L0/L1

Capture

Registration Capture

L0/L1

Cryptography

Supported algorithms:

Usage

Algorithm

Key Size

Storage

Encryption of biometrics - Session Key

AES

>=256

No storage, Key is created with TRNG/DRBG inside FTM

Encryption session key data outside of FTM

RSA OAEP

>=2048

FTM trusted memory

Encryption session key data outside of FTM

ECC curve 25519

>=256

FTM trusted memory

Biometric Signature

RSA

>=2048

Key never leaves FTM created and destroyed

Biometric Signature

ECC curve 25519

>=256

Key never leaves FTM created and destroyed

Secure Boot

RSA

>=256

FTM trusted memory

Secure Boot

ECC curve 25519

>=256

FTM trusted memory

{% hint style="info" %} No other ECC curves are supported. {% endhint %}

Signature

Request/Response

Block

Signature Key

Device Discovery Response

Device Info

NA as it will not be signed

Device Discovery Response

Digital ID

NA as it will not be signed

Device Info Response

Device Info

NA in case of unregistered device
Device Key in case of registered device

Device Info Response

Digital ID

For L0 device using device key
For L1 device using FTM chip key

Capture Response

Data

Device key is used

Capture Response

Digital ID

FTM chip key is used

Registration Capture Response

Data

Device key is used

Registration Capture Response

Digital ID

For L0 device using device key
For L1 device using FTM chip key

Android SBI Specification

This section explains the mechanism for the SBI devices to communicate in the android operating system.

Status

Draft document V 0.9

Approach

Device Discovery

callbackId should be set to the appId, and can not be empty in android.

Device Info

deviceInfo: callbackId should be set to the appId, can not be empty in android.

Capture

URI must be invalidated right after the read.

rCapture

The content provider should not support insert, update, delete

Device Stream

On receiving rCapture request MDS must show the stream within its UI in the foreground.

Security

Ensure to set the correct authority in the manifest and set the android:exported as “False”

Android Tab Specs

Android 9 (API Level 28) and above with hardware-backed key store.

Error Codes

Code

Message

Success

100

Device not registered

101

Unable to detect a biometric object

102

Technical error during extraction.

103

Device tamper detected

104

Unable to connect to the management server

105

Image orientation error

106

Device not found

107

Device public key expired

108

Domain public key missing

109

Requested number of biometric (Finger/IRIS) not supported

110

Device is not ready

111

Device is Busy

112

Invalid Transaction ID

5xx

Custom errors. The device provider is free to choose his error code and error messages.