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
Updated the FTM criteria 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 Biometric Specification and the old specification is now in 0.9.5 Biometric Specifications 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
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
Added the section on Android SBI Specification​
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.
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/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)
The supported algorithm and curves are listed here​
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 (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.
The validity of the chip certificate can not exceed 20 years from the date of manufacturing.
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.
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).
Accepted Values for Digital ID
Parameters
Description
serialNo
Serial number of the device.
This value should be same as printed on the device (Refer Physical ID).
make
Brand name.
This value should be the same as printed on the device (Refer to Physical ID).
model
Model of the device.
This value should be the same as printed on the device (Refer to Physical ID).
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"
"Biometric Device" - is a special type and is used in case you are looking for any biometric device.
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
Relevant errors as defined under the error section of this document.
error.errorCode
A standardized error code is defined in the error code section.
error.errorInfo
Description of the error that can be displayed to the end user. Multi-lingual support.
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.
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
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.
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
NA
Accepted Values for Device Info Request
NA
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
Relevant errors as defined under the error section of this document.
error.errorCode
A standardized error code is defined in the error code section.
error.errorInfo
Description of the error that can be displayed to the end user. Multi-lingual support.
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".
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
The payloads are JSON in both cases and are part of the body.
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.
  }
}
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".
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 providing the service.
The different IDs should be used for every successful auth.
So even if the transaction fails after auth we expect this number to be unique.
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
1
61 - 80
2
41 - 60
3
21 - 40
4
0 - 20
5
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
Unique transaction id sent in request
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
Relevant errors as defined under the error section of this document.
error.errorCode
Standardized error code defined in the error code section.
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:

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 FTM criteria 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 Biometric Specification and the old specification is now in 0.9.5 Biometric Specifications 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	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	Added the section on Android SBI Specification

Parameters	Description
serialNo	Serial number of the device. This value should be same as printed on the device (Refer Physical ID).
make	Brand name. This value should be the same as printed on the device (Refer to Physical ID).
model	Model of the device. This value should be the same as printed on the device (Refer to Physical ID).
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.

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	Relevant errors as defined under the error section of this document.
error.errorCode	A standardized error code is defined in the error code section.
error.errorInfo	Description of the error that can be displayed to the end user. Multi-lingual support.

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	Relevant errors as defined under the error section of this document.
error.errorCode	A standardized error code is defined in the error code section.
error.errorInfo	Description of the error that can be displayed to the end user. Multi-lingual support.

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 providing the service. The different IDs should be used for every successful auth. So even if the transaction fails after auth we expect this number to be unique.
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.

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	Unique transaction id sent in request
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	Relevant errors as defined under the error section of this document.
error.errorCode	Standardized error code defined in the error code section.
error.errorInfo	Description of the error that can be displayed to the end-user. Multi-lingual support.