All ABIS operations are via. a message queue and are asynchronous. The data sent in ABIS can be byte array or text based on a configure in registration processor.
ABIS must get biometric data from referenceURL, process it and store it locally within the ABIS reference database. More details about the refernceURL is mentioned in our referenceURL section.
referenceId must not be active prior to this operation i.e., it must not have been used before this operation.
De-duplication must not be performed in this operation.
MOSIP will provide biometric data in CBEFF format to ABIS as a response of referenceURL and the data will be encrypted and encoded as mentioned below.
The reference URL is MOSIP's datashare URL which is generated based on a policy defined by MOISP's adopter.
The referenceURL is authenticated and authorized; ABIS needs to send a JWT token inside the request header COOKIE
The referenceURL will be active for a certain time as decided by the MOSIP adopter
The data sent in the referenceURL will be encrypted
Authentication Token
As mentioned above in order to access the request URL the ABIS system needs to send a JWT token inside the request header COOKIE. In order to get the token ABIS needs to call MOSIP's AuthN & AuthZ API with Client ID & Secret Key by passing the credentials (clientid, secretkey and appid) which would be provided by the System Integrator (SI).
Below is the sample API details for getting the authentication token. More details about the API is available in our AuthN & AuthZ document.
Sample Request URL
POST https://{base_url}/v1/authmanager/authenticate/clientidsecretkey
The P12 file for the above encrypted CBEFF file is available here: cbeff.p12.
The other details for the p12 file are:
certificate.keystore=PKCS12
certificate.alias=cbeff
certificate.password=password
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.1.5.5 or prior versions
The data downloaded would be base64 encoded. Hence, after decoding the data will be in the below format. It will be divided in two Parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into two parts,
The first part is the Certificate Thumbprint i.e. the key identifier which is the first 32 bytes in Block 1.
The second part is the Encrypted Random AES Key which is encrypted with RSA OAEP - SHA256-MFG1. This cosistutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
The 1st part is the Encrypted data, encrypted using AES GCM PKCS5Padding.
The 2nd part is IV/Nonce i.e. the last 32 bytes appended after encrypted data.
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions
The data downloaded would be URL safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided in two Parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into three parts,
The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.
The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.
The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This cosistutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
The 1st part is the random 32 bytes which will be used as AAD in AES encryption(first 32 bytes). From this 32 bytes AAD data, the first 12 bytes is IV/Nonce.
The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.
All Possible Error codes and Messages from Datashare URL
Please note that, for all the functional failures MOSIP sends response code as 200.
Identify
All Insert requests added to the queue earlier must be serviced by ABIS when performing an Identify request.
Identify request provides a 1:N comparison. The given input is compared either against the gallery passed or if the gallery is not specified the entire database.
The input for comparison can be provided by referenceID or referenceURL.
If the referenceID is given it is used as the preferred option. The given referenceID must be existing in the ABIS database else ABIS will throw and error.
If the referenceID is omitted or NULL and the referenceURL is passed the ABIS retrieves the biometrics provided in the referenceURL and compares the same against either a gallery or its database.
If in case, both referenceID and referenceURL are missing ABIS throws an error.
We are not using the referenceURL in Identify request for our current implementation. Hence, it will be an empty string for Identify request. MOSIP adopters can have customized work-flows where the referenceURL can be used.
Identify request should give all candidates which are considered as a match based on ABIS thresholds.
This request should not match against referenceID that is not in the reference database.
The response now has a section for analytics that contains key value pairs. Values can be JSON objects also. The contents of the analytics section will be agreed upon by the MOSIP adopter with the ABIS provider. Scores are also moved to this section and are not mandatory response parameters any more.
Ordering or ranking of results is not explicitly specified and can be agreed upon between the MOSIP adopter and the ABIS provider.
The flags section of the request can be used to customize or control ABIS behavior by sending specific key value pairs.
"targetFPIR" or "maxResults" are examples of such flags that can alter the ABIS behavior. These are optional attributes for MOSIP during an identify request. MOSIP expects the adopters to define these parameters based on the accuracy expectations and the work-flow requirements. These can be set at the ABIS configuration level and need not be part of the individual request at all.
To give an example, please find the following calculation for targetFPIR - which is the error rate at which identification requests are expected to return non-empty candidate list.
{
"id": "mosip.abis.identify",
"version": "1.1",
"requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
"requesttime": "2020-03-29T07:01:24.692Z",
"referenceId": "987654321-89AB-CDEF-0123-456789ABCDEF",
"referenceURL": "",//will be an empty string, if not used
"flags": { //optional
//maxResults is an example and not a prescribed flag
"maxResults": "10",
//targetFPIR is an example and not a prescribed flag
"targetFPIR": "30",
//there can be more following this
"flag1": "value1",
"flag2": "value2"
},
"gallery": {
"referenceIds": [
{
"referenceId": "2abe7b7d-b58a-4466-a006-c79297281123"
},
{
"referenceId": "7acce7b7d-b58a-4466-a006-c79297281456"
},
{
"referenceId": "3bce7b7d-b58a-4466-a006-c79297281678"
},
{
"referenceId": "5cce7b7d-b58a-4466-a006-c79297281098"
},
{
"referenceId": "2cce7b7d-b58a-4466-a006-c79297281321"
}
]
}
}
Success Response
{
"id": "mosip.abis.identify",
"requestId": "01234567-89AB-CDEF-0123-456789ABCDEF",
"responsetime": "2020-03-29T07:01:24.692Z",
"returnValue": "1",
"candidateList": {
"count": "1",
"candidates": [
{
"referenceId": "7acce7b7d-b58a-4466-a006-c79297281456",
"analytics": {
//internalScore is an example and not prescribed
"internalScore": "112",
//confidence is an example and not prescribed
"confidence": "90",
//there can be more following this
"key1": "value1",
"key2": "value2"
},
// modality wise analytics
"modalities": [
{
"biometricType": "FIR",
"analytics": {
"confidence": "90",
"internalScore": "112",
"key1": "value1",
"key2": "value2"
}
},
{
"biometricType": "IIR",
"analytics": {
"confidence": "90",
"internalScore": "112",
"key1": "value1",
"key2": "value2"
}
},
{
"biometricType": "FID",
"analytics": {
"confidence": "90",
"internalScore": "112",
"key1": "value1",
"key2": "value2"
}
}
]
}
]
"analytics": {
//This is a optional section
//Data in this section can be agreed upon between the MOSIP adopter and the ABIS Provider
}
}
}