M
M
MOSIP Docs
Search…
SBI Specification
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.
API specification version: 1.0
Published Date: June 23, 2021
This specification will be used in MOSIP LTS (1.2.0) release onwards with backward compatibility to 0.9.5 MDS specification.
MDS is now formally renamed as SBI.

Revision Note

Publish Date
Revision
June 23, 2021
This is the first formal publication of this document as a version-ed specification. Earlier drafts are superseded by this document.

Glossary of Terms

Key
Description
MOSIP Devices
A hardware capable of capturing biometric information. All devices that collect biometric data for MOSIP should operate within the specification of this document.
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.
SBI 2.0 Certified Device / SBI 2.0 Device
A device certified as capable of performing all biometric functionalities (capture, processing), signing and encryption in line with this spec in its hardware trusted zone/FTM.
SBI 1.0 Certified Device / SBI 1.0 Device
A device certified as one where the biometric functionalities (capture, processing), signing and encryption is done on the host machine software zone as a separate service (protected from users or other OS-level applications) or at the device driver level.
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 SBI 1.0/SBI 2.0 respective compliance. The entity is expected to keep this certificate in secure possession in an HSM. All the individual device trust certificates are issued using this certificate as the root. This certificate is issued by the countries in conjunction with MOSIP.
Management Server
A server run by the device provider to manage the life cycle of the biometric devices.
FPS
Frames Per Second
Signature
All signature should be as per RFC 7515. Header - The attribute with "alg" set to RS256 and x5c set to base64urlencoded certificate. Payload - Byte array of the actual data, always represented as base64urlencoded. Signature - Base64urlencoded signature bytes
ISO format timestamp
ISO 8601 with format yyyy-mm-ddTHH:MM:ssZ (Example: 2020-12-08T09:39:37Z). This value should be in UTC (Coordinated Universal Time).
Registration
The process of applying for a Foundational Id.
Auth
The process of verifying one’s identity.
KYC
Know Your Customer is the process of providing consent to perform profile verification and update.

Device Specification

The specification documentation provides compliance guidelines to devices for them 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
For details about biometric specifications in MOSIP please view the page MOSIP Biometric Specification.

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.
Trust Level
Description
SBI 1.0
The trust is provided at the software level. No hardware related trust exists. This type of compliance is allowed to be used in controlled environments such as registration, however, it's recommended to use SBI 2.0 and above in all scenarios.
SBI 2.0
The trust is provided by a secure chip or FTM with a secure execution environment. This type of compliance is used in uncontrolled environments such as Authentication or e-KYC. Usage of SBI 1.0 devices are not allowed in such scenarios.

Foundational Trust Module (FTM)

Applicable for SBI 2.0 and above.
The foundational trust module would be created using a secure microprocessor capable of performing all required biometric processing and secure storage of keys. FTM could be a single chip (secure microprocessor), or a combination of chips or a set of hardware components that collectively offer the required trust levels. 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 implementation of the cryptographic algorithm.
  • The module can perform a cryptographically validate-able 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 violation 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.
    • 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 trusts are 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)
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 of the states - "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 is expected to operate or reach an inoperable state and 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 an FTM provider approved 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 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 from the FTM provider. 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 device is expected to be whitelisted with a fully capable PKI and secure storage of keys at the hardware.
  • SBI 1.0 - A device can obtain SBI 1.0 certification when it uses software level cryptographic libraries with no secure boot or FTM.
  • SBI 2.0 - A device can obtain SBI 2.0 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,
1
{
2
"serialNo": "Serial number",
3
"make": "Make of the device",
4
"model": "Model of the device",
5
"type": "Type of the biometric device",
6
"deviceSubType": "Subtypes of the biometric device",
7
"deviceProvider": "Device provider name",
8
"deviceProviderId": "Device provider id",
9
"dateTime": "Current datetime in ISO format"
10
}
Copied!
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 SBI 1.0 compliant devices that have the purpose (explained below during device registration) as "Registration". SBI 1.0 devices would sign the digital Id with the device key.
A signed digital ID would look as follows,
1
"digitalId": "base64urlencoded(header).base64urlencoded(payload).base64urlencoded(signature)"
Copied!
The header in the digital id would have,
1
"alg": "RS256",
2
"typ": "JWT",
3
"x5c": "<Certificate of the FTM chip, If in case the chain of certificates are sent then the same will be ignored">
Copied!
MOSIP assumes that the first certificate in the x5c is the FTM's chip public certificate issued by the FTM root certificate.
Unsigned digital ID would look as follows,
1
"digitalId": "base64urlencoded(payload)"
Copied!
Payload is the Digital ID JSON object.
For an SBI 1.0 device that hasn’t obtained a certificate from the management server (deviceStatus = Not Registered), the digital id will be unsigned. In all other scenarios, except for a device discovery call (please see sections below), the digital ID will be signed either by the FTM key (SBI 2.0) or the device key (SBI 1.0).
Allowed Values
Parameters
Description
serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
make
This represents the brand name of the device. This value should be the same as the value printed on the device (Refer Physical ID).
model
This represents the model of the device. This value should be the same as the value printed on the device (Refer Physical ID).
type
This represents the type of the device. Currently, the allowed values here are "Finger", "Iris" or "Face". More types can be added based on the adopter's implementation.
deviceSubType
This represents the device subtype that is based on the device type. For Finger - "Slap", "Single" or "Touchless" For Iris - "Single" or "Double" For Face - "Full face"
deviceProvider
This represents the name of the device provider. The device provider should be a legal entity in the country.
dateTime
This contains the time during the issuance of an identity. 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 (device key) for various signing purposes. For SBI 2.0, the device keys are created by the device providers inside the FTM. For SBI 1.0 the device keys must be generated within the TPM or the Windows Keystore of the host machine. The device keys are used for signing the biometric.
Once the device is deployed in the field/registration centre, during the initialisation, a certificate signing request (CSR) corresponding to the Device Key is generated and sent to the device management server. After necessary validations of the device, the device provider authorises the device by issuing a certificate.
The device key is rotated frequently based on various scenarios,
  • When a device is connected first time to the host
  • When the key rotation policy condition is met
  • Any other requirements from adopter/device provider
All key rotation commands are issued by the device management server.
By default, MOSIP recommends 30 days key rotation policy for the device key.
More details of the signing and its usage will be here.

FTM Key

Applicable for SBI 2.0 and above.
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 to the device providers and the partners. This key is used to encrypt the biometric data. Details of the encryption are listed below. We recommend rotating this key every 1 year.

Device Trust Validation

Following is an example device trust validation flow illustrated using an imaginary company "ABC".

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 API’s 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 abstraction to the specifics.

Device Discovery Request

1
{
2
"type": "type of the device",
3
"specVersion": "SBI specification version"
4
}
Copied!

Allowed Values

Parameters
Description
type
This represents the type of device. Allowed values here are "Biometric Device", "Finger", "Face" or "Iris". "Biometric Device" - is a special type and used in case you are looking for "any" biometric device.
specVersion
This represents the spec version of the SBI. This is a mandatory parameter in SBI 1.0, but when requested the response the SBI supporting this spec version should respond to the discovery call.

Device Discovery Response

1
[
2
{
3
"serialNo": "Printed Serial Number of the device",
4
"deviceStatus": "Device status",
5
"certification": "Certification level",
6
"serviceVersion": "Device service version",
7
"deviceSubId": ["Array of supported device sub Ids"],
8
"callbackId": "Base URL to reach to the device",
9
"digitalId": "Unsigned Digital ID of the device",
10
"specVersion": ["Array of supported SBI specification version"],
11
"purpose": "Auth or Registration",
12
"error": {
13
"errorCode": "101",
14
"errorInfo": "Invalid JSON Value Type For Discovery.."
15
}
16
},
17
...
18
]
Copied!

Allowed Values

Parameters
Description
deviceStatus
Allowed values are "Ready", "Busy", "Not Ready", and "Not Registered". "Not Registered" denotes that the device does not have a valid certificate issued by the device provider for the device.
certification
Allowed values are "SBI 1.0" or "SBI 2.0" based on the level of certification.
serviceVersion
Device service version.
serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
deviceSubId
Allowed values are 0, 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 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 callback URL takes precedence over future request as a base URL.
digitalId
Digital ID as per the Digital ID definition but it will not be signed.
specVersion
Array of supported SBI specification version. 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
Standardized error code.
error.errorInfo
Description of the error that can be displayed to the end-user. It should have 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:
1
SBIDISC http://127.0.0.1:<device_service_port>/device
2
HOST: 127.0.0.1: <device_service_port>
3
EXT: <app name>
Copied!
HTTP Response:
1
HTTP/1.1 200 OK
2
CACHE-CONTROL:no-store
3
LOCATION:http://127.0.0.1:<device_service_port>
4
Content-Length: length in bytes of the body
5
Content-Type: application/json
6
Connection: Closed
Copied!
  • 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

All devices on an android device should listen to the following intent "io.mosip.device".
Upon invocation of this intent, the devices are expected to respond with the JSON response filtered by the respective type.
In Android, the CallbackId would be set to the appId. So, the caller will create the intent "appId.Info" or "appId.Capture".

IOS

All device on an IOS device would respond to the URL schema as follows,
1
SBIDISC://<call-back-app-url>?ext=<caller app name>&type=<type as defined in MOSIP device request>
Copied!
If a MOSIP compliant device service app exists then the URL would launch the service. The service in return should respond to the caller using the call-back-app-URL with the base64 encoded JSON as the URL parameter for the key data.
  • In IOS there are restrictions to have multiple apps registering to the same URL schema.
  • callbackId would be set to the device service app name. So, the caller has to call appnameInfo or appnameCapture as the URL scheme.

Device Info

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

Device Info Request

1
{
2
"type": "type of the device",
3
"specVersion": "SBI specification version"
4
}
Copied!

Allowed Values

Parameters
Description
type
This represents the type of device. This is a mandatory parameter in SBI 1.0. Allowed values here are "Biometric Device", "Finger", "Face" or "Iris". "Biometric Device" - is a special type and used in case you are looking for "any" biometric device.
specVersion
This represents the spec version of the SBI. This is a mandatory parameter in SBI 1.0, but when requested the response the SBI supporting this spec version should respond to the discovery call.

Device Info Response

1
[
2
{
3
"deviceInfo": {
4
"deviceStatus": "Current status",
5
"serialNo": "Printed Serial Number of the device",
6
"firmware": "Firmware version",
7
"certification": "Certification level",
8
"serviceVersion": "Device service version",
9
"deviceSubId": ["Array of supported device sub Ids"],
10
"callbackId": "BaseURL to reach to the device",
11
"digitalId": "Signed digital id as described in the digital id section of this document.",
12
"env": "Target environment",
13
"purpose": "Auth or Registration",
14
"specVersion": ["Array of supported SBI specification version"],
15
},
16
"error": {
17
"errorCode": "106",
18
"errorInfo": "Device not found"
19
}
20
}
21
...
22
]
Copied!
The final JSON is signed with the JSON Web Signature using the device key.
So the API would respond in the following format,
1
[
2
{
3
"deviceInfo": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
4
"error": {
5
"errorCode": "106",
6
"errorInfo": "Device not found"
7
}
8
}
9
]
Copied!

Allowed Values

Parameters
Description
deviceInfo
The deviceInfo object is sent as JSON Web Token (JWT). For devices that do not have a valid certificate issued by the device provider, the deviceInfo will be unsigned. For devices that are registered, the deviceInfo will be signed using the device key.
deviceInfo.deviceStatus
This is the current status of the device. Allowed values are "Ready", "Busy", "Not Ready", and "Not Registered". "Not Registered" denotes that the device does not have a valid certificate issued by the device provider against the device.
deviceInfo.firmware
Exact version of the firmware (SBI 2.0). In the case of SBI 1.0 this is the same as serviceVersion.
deviceInfo.certification
Allowed values are "SBI 1.0" or "SBI 2.0" based on the level of certification.
deviceInfo.serviceVersion
Version of the SBI specification that is supported.
deviceInfo.serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
deviceInfo.deviceSubId
Allowed values are 0, 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 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 callback URL takes precedence over future requests as a base URL.
deviceInfo.digitalId
The digital id as per the digital id definition. For SBI 1.0 devices that are yet to obtain a certificate from the device provider, the digitalId will be unsigned. For SBI 1.0 devices with valid certificates issued by the provider, the digital id will be signed using the device key. For SBI 2.0 devices, the digital id will be always signed using the FTM key.
deviceInfo.env
This represents the target environment. For devices that are not registered, the environment is "None". For devices that are registered, send the environment in which it is registered. Allowed values are "Staging", "Developer", "Pre-Production" or "Production".
deviceInfo.purpose
Purpose of the device in the MOSIP ecosystem. Allowed values are "Auth" or "Registration".
deviceInfo.specVersion
Array of supported SBI specification version. 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
Standardized error code.
error.errorInfo
Description of the error that can be displayed to the end-user. It should have 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:
1
SBIINFO http://127.0.0.1:<device_service_port>/info
2
HOST: 127.0.0.1:<device_service_port>
3
EXT: <app name>
Copied!
HTTP Response:
1
HTTP/1.1 200 OK
2
CACHE-CONTROL:no-store
3
LOCATION:http://127.0.0.1:<device_service_port>
4
Content-Length: length in bytes of the body
5
Content-Type: application/json
6
Connection: Closed
Copied!
The payloads are JSON in both cases and are part of the body.

Android

An android device should listen to the following intent "appId.Info".
Upon invocation of this intent, the devices are expected to respond with the JSON response filtered by the respective type.

IOS

An IOS device would respond to the URL schema as follows,
1
SBIINFO://<call-back-app-url>?ext=<caller app name>&type=<type as defined in MOSIP device request>
Copied!
If a MOSIP compliant device service app exists then the URL would launch the service. The service in return should respond to the call using the call-back-app-URL with the base64 encoded JSON as the URL parameter for the key data.
In IOS there are restrictions to have multiple apps registering to the same URL schema.

Capture

The capture request would be used to capture a biometric from MOSIP compliant devices by the applications for authentication. The capture 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 status as "Busy".

Capture Request

1
{
2
"env": "Target environment",
3
"purpose": "Auth",
4
"specVersion": "Expected version of the SBI spec",
5
"timeout" : "Timeout for capture",
6
"captureTime": "Time of capture request in ISO format",
7
"domainUri": "URI of the auth server",
8
"transactionId": "Transaction Id for the current capture",
9
"bio": [
10
{
11
"type": "Type of the biometric data",
12
"count": "Finger/Iris count, in case of face max is set to 1",
13
"bioSubType": ["Array of subtypes"],
14
"requestedScore": "Expected quality score that should match to complete a successful capture. This value will be scaled from 0 - 100 for NFIQ v1.0. The logic for scaling is mentioned below.",
15
"serialNo": "Physical Serial Number of the device",
16
"deviceSubId": "Specific Device Sub Id",
17
"previousHash": "Hash of the previous block"
18
}
19
],
20
"customOpts": {
21
//max of 50 key-value pair.
22
//This is so that vendor-specific parameters can be sent if necessary.
23
//The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications.
24
//Vendors are free to include additional parameters and fine-tuning parameters.
25
//None of these values should go undocumented by the vendor.
26
//No sensitive data should be available in the customOpts.
27
}
28
}
Copied!
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

Parameters
Description
env
This represents 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. The allowed value is "Registration".
specVersion
Expected version of SBI specification.
timeout
Max time the app will wait for the capture. It's expected that the API will respond before timeout if the requested score is met, or with the best frame at the timeout. All timeouts are in milliseconds.
captureTime
Time of capture in ISO format. The time is as per the requesting application.
domainUri
URI of the authentication server. This can be used to federate across multiple providers or countries or unions.
transactionId
Unique ID for the transaction. This is an internal Id to the application that's providing the service. The different id should be used for every transaction. 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
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.serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
bio.deviceSubId
Allowed values are 0, 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 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). Wherever possible SBI must detect if the placement of biometrics is not in sync with the deviceSubId. For example, if the deviceSubId is selected as 1 and if a right slap is presented instead of left, SBI must provide appropriate messages.
bio.previousHash
For the first capture the previousHash is 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 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 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
"bio.bioSubType" is a mandatory parameter for Capture request. For cases where “any” biometrics are expected, an array of UNKNOWN can be passed equally to the count specified in bio.count.
The SBI must make sure of the following,
  • Must not allow the capture of the same biometrics segment wherever possible.
  • In case of fingerprint, if a multi-finger scanner is used, and if bioSubType is passed as UNKNOWN, capture must return fingers in the order starting from IndexFinger to LittleFinger.

Capture Response

1
{
2
"biometrics": [
3
{
4
"specVersion": "SBI spec version",
5
"data": { //data block in JWT format signed using device key
6
"digitalId": "Digital Id as described in this document signed using FTM key (SBI 2.0)",
7
"deviceServiceVersion": "SBI version",
8
"bioType": "Finger",
9
"bioSubType": "UNKNOWN",
10
"purpose": "Auth",
11
"env": "Target environment",
12
"domainUri": "URI of the auth server",
13
"bioValue": "Encrypted with session key and base64urlencoded biometric data",
14
"transactionId": "Unique transaction id",
15
"timestamp": "Current datetime in ISO format",
16
"requestedScore": "Floating point number to represent the minimum required score for the capture",
17
"qualityScore": "Floating point number representing the score for the current capture"
18
},
19
"hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
20
"sessionKey": "Session key used for encrypting bioValue, encrypted with MOSIP public key (dynamically selected based on the URI) and base64urlencoded",
21
"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",
22
"error": {
23
"errorCode": "101",
24
"errorInfo": "Invalid JSON Value"
25
},
26
"additionalInfo": {
27
//Additional information can be sent by the SBI in key value pair.
28
//max of 50 key value pair.
29
//Vendors are free to include any number of additional parameters.
30
//None of these values should go undocumented by the vendor.
31
//No sensitive data should be available here.
32
}
33
},
34
{
35
"specVersion" : "SBI spec version",
36
"data": { //data block in JWT format signed using device key
37
"digitalId": "Digital Id as described in this document signed using FTM key (SBI 2.0)",
38
"deviceServiceVersion": "SBI version",
39
"bioType": "Finger",
40
"bioSubType": "Left IndexFinger",
41
"purpose": "Auth",
42
"env": "Target environment",
43
"domainUri": "URI of the auth server",
44
"bioValue": "Encrypted with session key and base64urlencoded biometric data",
45
"transactionId": "Unique transaction id",
46
"timestamp": "Current datetime in ISO format",
47
"requestedScore": "Floating point number to represent the minimum required score for the capture",
48
"qualityScore": "Floating point number representing the score for the current capture"
49
},
50
"hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data before encryption)",
51
"sessionKey": "Session key used for encrypting bioValue, encrypted with MOSIP public key (dynamically selected based on the URI) and base64urlencoded",
52
"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",
53
"error": {
54
"errorCode": "101",
55
"errorInfo": "Invalid JSON Value"
56
},
57
"additionalInfo": {
58
//Additional information can be sent by the SBI in key value pair.
59
//max of 50 key value pair.
60
//Vendors are free to include any number of additional parameters.
61
//None of these values should go undocumented by the vendor.
62
//No sensitive data should be available here.
63
}
64
}
65
]
66
}
Copied!

Allowed Values

Parameters
Description
specVersion
Version of the SBI 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 as per the digital id definition in JWT format. For SBI 1.0 devices, the digital id will be signed using the device key. For SBI 2.0 devices, the digital id will be signed using the FTM key.
data.deviceServiceVersion
SBI 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 value is "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 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.
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 before encryption)
sessionKey
The session key (used for the encrypting of the bioValue) is encrypted using the MOSIP public certificate with RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING algorithm and then base64-URL-encoded.
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
Relevant errors as defined under the error section of this document.
error.errorCode
Standardized error code.
error.errorInfo
Description of the error that can be displayed to the end-user. It should have multi-lingual support.
The entire data object is sent in a JWT format. So, the data object will look like,
1
"data" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)
Copied!
The payload is defined as the entire byte array of the data block.

Windows/Linux

The applications that want to capture biometric data from a MOSIP device could do so by sending the HTTP request to the supported port range.
HTTP Request:
1
CAPTURE http://127.0.0.1:<device_service_port>/capture
2
HOST: 127.0.0.1: <apps port>
3
EXT: <app name>
Copied!
HTTP Response:
1
HTTP/1.1 200 OK
2
CACHE-CONTROL:no-store
3
LOCATION:http://127.0.0.1:<device_service_port>
4
Content-Length: length in bytes of the body
5
Content-Type: application/json
6
Connection: Closed
Copied!
The payloads are JSON in both cases and are part of the body.

Android

All devices on an android device should listen to the following intent appid.capture. Upon this intent, the devices are expected to respond with the JSON response filtered by the respective type.

IOS

All devices on an IOS device would respond to the URL schema as follows.
1
APPIDCAPTURE://<call-back-app-url>?ext=<caller app name>&type=<type as defined in MOSIP device request>
Copied!
If a MOSIP compliant device service app exists then the URL would launch the service. The service in return should respond to the call using the call-back-app-URL with the base64 encoded JSON as the URL parameter for the key data.

Device Stream

The device would open a stream channel to send the live video streams. This would help when there is an assisted operation to collect biometric. Please note the stream API’s are available only for the registration environment.
This API is visible only for the devices that are registered for "Registration" purpose.

Device Stream Request

1
{
2
"type": "type of the device",
3
"specVersion": "SBI specification version",
4
"serialNo": "Printed Serial Number of the device",
5
"deviceSubId": "Specific device sub Id",
6
"timeout": "Timeout for stream"
7
"dimensions": "Optional parameter for handling specific requirements such as exception photostream. Please refer to the stream frame guidelines."
8
}
Copied!

Allowed Values

Parameters
Description
type
This represents the type of device. This is a mandatory parameter in SBI 1.0. Allowed values here are "Biometric Device", "Finger", "Face" or "Iris". "Biometric Device" - is a special type and used in case you are looking for "any" biometric device.
specVersion
This represents the spec version of the SBI. This is a mandatory parameter in SBI 1.0, but when requested the response the SBI supporting this spec version should respond to the discovery call.
serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
deviceSubId
Allowed values are 0, 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 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). Wherever possible SBI must detect if the placement of biometrics is not in sync with the deviceSubId. For example, if the deviceSubId is selected as 1 and if a right slap is presented instead of left, SBI must provide appropriate messages.
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.
dimensions
This is an optional parameter for handling specific requirements such as photo stream during exception. Please refer to the stream frame guidelines. Format: mmmm. For example, value 6040 denotes 60mm(width) X 40mm(height) of the stream window.

Device Stream Response

Live video stream with quality of 3 frames per second or more using M-JPEG.
The preview should have quality markings and segment marking. The preview would also be used to display an error message to the user screen. All error messages should be localized.
Preview must guide the resident on the correct placement of biometric on the sensor. It is recommended to use colour coding (Green for good placement, Red for incorrect placement) and audio, visual cues must be used.

Error Response for Device Stream

1
{
2
"error": {
3
"errorCode": "202",
4
"errorInfo": "No Device Connected."
5
}
6
}
Copied!

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:
1
STREAM http://127.0.0.1:<device_service_port>/stream
2
HOST: 127.0.0.1: <apps port>
3
EXT: <app name>
Copied!
HTTP Response: HTTP Chunk of frames to be displayed. Minimum frames 3 per second.

Android

No support for streaming

IOS

No support for streaming

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 of the individual, 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 the scale of 0-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 the devices that are compatible with the registration module. This API should not be supported by devices that are compatible with authentication.

Registration Capture Request

1
{
2
"env": "Target environment",
3
"purpose": "Registration",
4
"specVersion": "Expected SBI spec version",
5
"timeout": "Timeout for registration capture",
6
"captureTime": "Time of capture request in ISO format",
7
"transactionId": "Transaction Id for the current capture",
8
"bio": [
9
{
10
"type": "Type of the biometric data",
11
"count": "Finger/Iris count, in case of face max is set to 1",
12
"bioSubType": ["Array of subtypes"], //Optional
13
"exception": ["Finger or Iris to be excluded"],
14
"requestedScore": "Expected quality score that should match to complete a successful capture.",
15
"serialNo": "Printed Serial Number of the device",
16
"deviceSubId": "Specific device Id",
17
"previousHash": "Hash of the previous block"
18
}
19
],
20
"customOpts": {
21
//max of 50 key-value pair.
22
//This is so that vendor-specific parameters can be sent if necessary.
23
//The values cannot be hardcoded and have to be configured by the apps server and should be modifiable upon need by the applications.
24
//Vendors are free to include additional parameters and fine-tuning parameters.
25
//None of these values should go undocumented by the vendor.
26
//No sensitive data should be available in the customOpts.
27
}
28
}
Copied!
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.

Allowed Values

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. The allowed value is "Registration".
specVersion
Expected version of SBI specification.
timeout
Max time the app will wait for the capture. It's expected that the API will respond before timeout if the requested score is met, or with the best frame at the timeout. 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 providing the service. The different id should be used for every transaction. So, even if the transaction fails we expect this number to be unique.
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"]
This is a mandatory parameter.
For cases where "any" biometrics are expected, an array of UNKNOWN can be passed equal to the count specified in bio.count.
The SBI must make sure not to allow the capture of the same biometrics segment wherever possible and in case of fingerprint, if a multi finger scanner is used, and if bioSubType is passed as UNKNOWN, capture must return fingers in the order starting from IndexFinger to LittleFinger.
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.
bio.serialNo
This represents the serial number of the device. This value should be the same as printed on the device (Refer Physical ID).
bio.deviceSubId
Allowed values are 0, 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 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). Wherever possible SBI must detect if the placement of biometrics is not in sync with the deviceSubId. For example, if the deviceSubId is selected as 1 and if a right slap is presented instead of left, SBI must provide appropriate messages. SBI must detect if the placement of biometrics is not in sync with the deviceSubId. For example, if the deviceSubId is selected as 1 and if a right slap is presented instead of left, SBI must provide appropriate messages.
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 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 the process. None of these values should go undocumented by the vendor. No sensitive data should be available in the customOpts.

Registration Capture Response

1
{
2
"biometrics": [
3
{
4
"specVersion": "SBI Spec version",
5
"data": {
6
"digitalId": "Digital id of the device as per the Digital Id definition, signed using FTM key (SBI 2.0) or the device key (SBI 1.0).",
7
"bioType": "Biometric type",
8
"deviceServiceVersion": "SBI version",
9
"bioSubType": "Left IndexFinger",
10
"purpose": "Registration",
11
"env": "Target environment",
12
"bioValue": "base64urlencoded biometrics (ISO format)",
13
"transactionId": "Unique transaction id sent in request",
14
"timestamp": "2019-02-15T10:01:57Z",
15
"requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100.",
16
"qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100."
17
},
18
"hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",
19
"error": {
20
"errorCode": "101",
21
"errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' } "
22
},
23
"additionalInfo": {
24
//Additional information can be sent by the SBI in key value pair.
25
//max of 50 key value pair.
26
//Vendors are free to include any number of additional parameters.
27
//None of these values should go undocumented by the vendor.
28
//No sensitive data should be available here.
29
}
30
},
31
{
32
"specVersion" : "SBI Spec version",
33
"data": {
34
"digitalId": "Digital id of the device as per the Digital Id definition, signed using FTM key (SBI 2.0) or the device key (SBI 1.0).",
35
"bioType" : "Finger",
36
"deviceServiceVersion": "SBI version",
37
"bioSubType": "Left MiddleFinger",
38
"purpose": "Registration",
39
"env": "Target environment",
40
"bioValue": "base64urlencoded biometric (ISO format)",
41
"transactionId": "Unique transaction id sent in request",
42
"timestamp": "2019-02-15T10:01:57Z",
43
"requestedScore": "Floating point number to represent the minimum required score for the capture. This ranges from 0-100",
44
"qualityScore": "Floating point number representing the score for the current capture. This ranges from 0-100"
45
},
46
"hash": "sha256 in hex format in upper case (previous "hash" + sha256 hash of the current biometric ISO data)",
47
"error": {
48
"errorCode": "101",
49
"errorInfo": "Invalid JSON Value Type For Discovery.. ex: {type: 'Biometric Device' or 'Finger' or 'Face' or 'Iris' }"
50
},
51
"additionalInfo": {
52
//Additional information can be sent by the SBI in key value pair.
53
//max of 50 key value pair.
54
//Vendors are free to include any number of additional parameters.
55
//None of these values should go undocumented by the vendor.
56
//No sensitive data should be available here.
57
}
58
}
59
]
60
}
Copied!

Allowed Values

Parameters
Description
specVersion
Version of the SBI 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 SBI 1.0 devices, the digital id will be signed using the device key. For SBI 2.0 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
SBI 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. The allowed value is "Registration".
data.bioValue
Base64-URL-encoded biometrics (in ISO format)
data.transactionId
Unique transaction id sent in request
data.timestamp
Time as per the biometric device. 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. Return NFIQ 2.0 scores for fingerprint.
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 error section of this document.
error.errorCode
Standardized error code.
error.errorInfo
Description of the error that can be displayed to the end-user. It should have 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:
1
RCAPTURE http://127.0.0.1:<device_service_port>/capture
2
HOST: 127.0.0.1: <apps port>
3
EXT: <app name>
Copied!
HTTP Response: HTTP response.

Android

No support for Registration Capture

IOS

No support for Registration Capture

Management Server and Management Client

As explained in section device trust validation the devices are expected to get connected with the management server and get a certificate issued by the device provider for its usage in the MOSIP ecosystem.

Management Server Functionalities and Interactions

The management server has the following objectives.
  1. 1.
    Validate the devices to ensure it's a genuine device from the respective device provider. This can be achieved using the device info and the certificates of the Foundational Trust Module.
  2. 2.
    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.
  3. 3.
    Ability to issue commands to the end device for
    1. 1.
      Cleanup of the device keys.
    2. 2.
      Collect device information to maintain, manage, support and upgrade a device remotely.
  4. 4.
    A central repository of all the approved devices from the device provider.
  5. 5.
    Safe storage of keys using HSM FIPS 140-2 Level 3. These keys are used to issue the device certificate upon registration of the device with the Management Server. The Management Server is created and hosted by the device provider outside of MOSIP software. The communication protocols between the SBI 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.
  6. 6.
    Should have the ability to push updates from the server to the client devices.
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.

Management Client

Management client is the interface that connects the device with the respective management server. This could be a separate library running within the SBI or a simple set of API definitions talking to the management server over HTTPS. 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.
  1. 1.
    For better and efficient handling of devices at large volume, we expect the devices to auto-register to the Management Server.
  2. 2.
    All communication to the server and from the server should follow the below properties.
    1. 1.
      All communication is digitally signed with the approved algorithms
    2. 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. 3.
      All requests should have timestamps attached in ISO format to the milliseconds inside the signature.
    4. 4.
      All communication back and forth should have the signed digital id as one of the attributes.
  3. 3.
    It's expected that the auto registration with the management server has an absolute way to identify and validate the devices.
  4. 4.
    The management client or SBI should be able to detect the devices in a plug and play model.
  5. 5.
    The management client must connect to the respective management server on defined frequencies along with the status of the certificate and the device itself. Key rotation commands or any other instructions to the SBI should be triggered from the server as a response to this status check query from the SBI/management client.
  6. 6.
    Should have the ability to detect if it's speaking to the right management server.
  7. 7.
    All upgrades should be verifiable and the client or SBI should have the ability to verify software upgrades.
  8. 8.
    Should not allow any downgrade of software.
  9. 9.
    Should not expose any API to capture biometric. The management server should have no ability to trigger a capture request.
  10. 10.
    No logging of biometric data is allowed. (Both in the encrypted and unencrypted format)

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. The encryption certificate is used to encrypt the bioValue of a capture API response.

Retrieve Encryption Certificate Request URL

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

Retrieve Encryption Certificate Request

1
{
2
"id": "io.mosip.auth.country.certificate",
3
"version": "certificate server api version as defined above",
4
"request": {
5
"data": {
6
"env": "target environment",
7
"domainUri": "uri of the auth server"
8
}
9
},
10
"requesttime": "current timestamp in ISO format"
11
}
Copied!
The request is sent in a JWT format. So the final request will look like this,
1
"request": {
2
"data": "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
3
}
Copied!

Allowed Values

Parameters
Description
request.data
The data object is sent as JSON Web Token (JWT).
request.data.env
The target environment for which you want to fetch the certificate. Allowed values are "Staging", "Developer", "Pre-Production" or "Production".
request.data.domainUri
unique URI per auth providers. This can be used to federate across multiple providers or countries or unions.

Encryption Certificate Response

1
{
2
"id": "io.mosip.auth.country.certificate",
3
"version": "certificate server api version as defined above",
4
"responsetime": "current datettime in ISO time format",
5
"response": [
6
{
7
"certificate": "base64urlencoded certificate as x509 V3 format"
8
}
9
]
10
}
Copied!
The entire response is sent in a JWT format. So the final response will look like this,
1
"response" : "base64urlencode(header).base64urlencode(payload).base64urlencode(signature)"
Copied!

Compliance

SBI 2.0 Certified Device / SBI 2.0 Device - A device certified as capable of performing all biometric functionalities (capture, processing), signing and encryption in line with this spec in its hardware trusted zone/FTM.
SBI 1.0 Certified Device / SBI 1.0 Device - A device certified as one where the biometric functionalities (capture, processing), signing and encryption is done on the host machine software zone as a separate service (protected from users or other OS-level applications) or at the device driver level.

Secure Provisioning

Secure provisioning applies to both the FTM and the Device providers.
  1. 1.
    The devices and FTM should have a mechanism to protect against fraudulent attempts to create or replicate.
  2. 2.
    The device and FTM trust should be programmed in a secure facility that is certified by the respective MOSIP adopters.
  3. 3.
    Organization should have a mechanism to segregate the FTM's and Devices built for MOSIP using cryptographically valid and repeatable processes.
  4. 4.
    All debug options within the FTM or device should be disabled permanently
  5. 5.
    All key creations needed for provisioning should happen automatically using FIPS 140-2 Level 3 or higher devices. No individual or a group or organization should have mechanisms to influence this behaviour.
  6. 6.
    Before the devices/FTM leave 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.

Compliance Level

API
Compatible
Device Discovery
SBI 1.0 / SBI 2.0
Device Info
SBI 1.0 / SBI 2.0
Capture
SBI 2.0
Registration Capture
SBI 1.0 / SBI 2.0

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
>=2048
FTM trusted memory
Secure Boot
ECC curve 25519
>=256
FTM trusted memory
No other ECC curves supported.

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