1 of 3

Registration Processor

Overview

Registration Processor (Regproc) is a backend processing engine to enable the ID Lifecycle management. The diagram below shows the Registration Processor along with the other modules that contribute in issuing a Unique Identification Number(UIN) for an individual. Internally, Regproc follows the SEDA architecture where data flows via multiple stages till the UIN is issued.

The relationship of Regproc with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow

Registration packets are uploaded by Registration Client to Packet Receiver.
After packet validation is done Regproc notifies pre-registration application using datasync service.
Quality of biometrics is checked using an external biometric SDK. This is done in Regproc's Quality Classifier stage.
Regproc shares biometric data with ABIS, Manual adjudication System and Verification System. The policy for sharing this data is fetched from PMS.
The above data is shared by providing a URL that partners use to fetch data. This URL is obtained from Datashare service.
Regproc's ABIS Middleware stage communicates with ABIS via Activemq. The ABIS performs deduplication and sends back result to the Queue.
Regproc stores and updates applicant demographic and biometric information in ID Repository. Also Activates or deactivates applicant UIN.
Regproc calls IDA Internal Authentication Service to authenticate Applicant(for update flow), introducer, operator and supervisor(when bio auth mode is used to create packet).
After the UIN is processed the Printing Stage calls Credential Service to create credential for print. This credential will be pushed to websub and the Printing systems will consume same.
The Notification Service is used to send email/sms notification to the applicant after the request processing is completed in server.
Regproc connects to external "Manual Adjudication System" via queue. Regproc sends applicant information required for adjudication in queue and external adjudication system consumes it. The data is shared from mosip to external adjudication system based on policy.
Regproc calls Key Manager for decrypting packet and for encrypting information.
Regproc uses Masterdata Service to validate center, machine, user etc.
Regproc connects to Virus Scanner for scanning packets in Packet Receiver Stage and Packet Uploader Stage
Each Stage in regproc calls Packet Manager to read information from packet.

Stages and services

The Registration Processor contains several stages and services.

The registration packet flows through the various stages depending on the type of flow. See Registration Flows and Stage Sequence.

Note: The Print Stage has been renamed as the Credential Requestor Stage. For further information, please click here.

Build and deploy

Refer to repo.

Configurations

Refer to Configuration Guide.

Developer Guide

To know more about the developer setup, read Registration Processor Developers Guide.

API

Refer API Documentation.

Source code

Github repo.

Manual Adjudication and Verification

When biometric duplicates are found in ABIS, the MOSIP system sends a request for manual adjudication to the Manual Adjudication System via a queue.
The system integrator can build the Manual Adjudication System, which would be listening to the MOSIP-to-ManualAdjudication queue for any manual adjudication requests and sends a response back in the ManualAdjudication-to-MOSIP system after verifying the data.
The data sent to the Manual Adjudication System is driven by a policy defined in MOSIP and the specification is similar to ABIS identify request.

The manual adjudication stage in registration processor performs the following functions:

Sends the applicant's demographic and biometric information (via queue + Datashare) to Manual Adjudication System (MAS).
Receives decision from MAS and accordingly forwards the packets.
If rejected, notifies the applicant.

Manual Adjudication request to Queue is as follows:

{
  "id": "mosip.manual.adjudication.adjudicate",
  "version": "1.0",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2019-02-14T12:40:59.768Z",
  "referenceId": "27847657360002520181208123456",
  "referenceURL": "<datashare url for regid>",
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "27847657360002520181208123451",
        "referenceURL": "<data share for matchedRegId>"
      },
      {
        "referenceId": "27847657360002520181208123452",
        "referenceURL": "<data share for matchedRegId>"
      }
    ],
    "addtional": [
      {
        "abisId": "<abis app code>",
        "response": "<abis response text received>"
      }
    ]
  }
}

Request parameters

requestId: request_id that is associated with each request present in reg_manual_verification table.

referenceId: reg_id that is associated with each request present in reg_manual_verification table.

referenceURL: Datashare url of biometrics, demographics(identity), audits, metainfo, documents of reg_id

gallery: contains the matched ref_id and referenceURL of matched ref_id.

Sample request

{
  "id": "mosip.manual.adjudication.adjudicate",
  "version": "1.0",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "referenceId": "10002100741000320210107125533",
  "requesttime": "2021-01-19T07:16:22.930Z",
  "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD",
  "addtional": null,
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "10002100741000120210107111325",
        "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202137493575474iefnvvsD"
      }
    ]
  }
}

Manual adjudication response structure from MAS

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2019-02-14T12:40:59.768Z",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "27847657360002520181208123451",
        "analytics": {
          //This section is optional 
          "primaryOperatorID": "110011",
          "primaryOperatorComments": "<comments provided by operator>",
          "secondaryOperatorID": "110012",
          "secondaryOperatorComments": "<comments provided by operator>",
          "key1": "value1",
          "key2": "value2"
        }
      }   
    ],
    "analytics": {
      // This section is optional
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Response parameters

returnValue: 1-Success, 2-Failure

candidateList: It contains matched candidate referenceIds, count and analytics.

Scenario: No match

Response structure- Not Matched (No Duplicate Profile found)

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "c278b2f1-29f7-4d1a-9fa7-e93e3f932816",
  "responsetime": "2022-09-23T06:31:31.7456782+00:00",
  "returnValue": "1",
  "candidateList": {
    "count": "0",
    "candidates": [],
    "analytics": null
  }
}

Scenario: There are matches

Response structure

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "58d5bb0e-e65e-4907-b452-81edbfd3ae46",
  "responsetime": "2022-09-23T06:33:11.9869624+00:00",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "10001100010000620220923053704",
        "analytics": {
          "primaryOperatorID": "admin",
          "primaryOperatorComments": "MATCHED",
          "Face": "F",
          "Finger": "Right_Thumb,Right_Index,Right_Middle,Right_Ring,Right_Little,Left_Thumb,Left_Index,Left_Middle,Left_Ring,Left_Little",
          "Iris": "Right_Iris,Left_Iris"
        }
      }
    ],
    "analytics": null
  }
}

Datashare structure

Datashare contains biometrics, identity documents, metainfo, audits related to particular rid and the datashare URL contains encrypted form of this data.

Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.

Sample Request URL

GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD

Sample Encrypted Response

The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions. The data downloaded would be URL-safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two parts after splitting using #KEY_SPLITTER#.

Block 1:

Block 1, i.e. the encrypted key data is again split into three parts, • The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.

• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.

• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

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

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

• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

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

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

Block 1:

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

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

Block 2:

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

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

Sample response in case of Authentication Failure

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

Possible Error Codes and messages from Datashare URL

Policy structure

partner Id: mpartner-default-adjudication policy Id: mpolicy-default-adjudication

{
  "shareableAttributes": [
    {
      "attributeName": "biometrics",
      "group": "CBEFF",
      "source": [
        {
          "attribute": "registration-client/NEW/individualBiometrics",
          "filter": [
            {
              "type": "Iris"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Finger"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Face"
            }
          ]
        }
      ],
      "encrypted": true,
      "format": "extraction"
    },
    {
      "attributeName": "fullName",
      "source": [
        {
          "attribute": "fullName"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "dateOfBirth",
      "source": [
        {
          "attribute": "dateOfBirth"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "gender",
      "source": [
        {
          "attribute": "gender"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "phone",
      "source": [
        {
          "attribute": "phone"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "email",
      "source": [
        {
          "attribute": "email"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine1",
      "source": [
        {
          "attribute": "addressLine1"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine2",
      "source": [
        {
          "attribute": "addressLine2"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine3",
      "source": [
        {
          "attribute": "addressLine3"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "region",
      "source": [
        {
          "attribute": "region"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "province",
      "source": [
        {
          "attribute": "province"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "city",
      "source": [
        {
          "attribute": "city"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "postalCode",
      "source": [
        {
          "attribute": "postalCode"
        }
      ],
      "encrypted": true
    }
  ],
  "dataSharePolicies": {
    "typeOfShare": "Data Share",
    "validForInMinutes": "30",
    "transactionsAllowed": "100000",
    "encryptionType": "none",
    "shareDomain": "datashare.datashare",
    "source": "Packet Manager"
  }
}

Configuration used in Manual adjudication

registration.processor.queue.manual.adjudication.request
registration.processor.queue.manual.adjudication.request.messageTTL
registration.processor.manual.adjudication.policy.id
registration.processor.manual.adjudication.subscriber.id
registration.processor.manual.adjudication.subscriber.id
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name
registration.processor.queue.manual.adjudication.request
registration.processor.queue.manual.adjudication.request.messageTTL
registration.processor.manual.adjudication.policy.id
registration.processor.manual.adjudication.subscriber.id
registration.processor.manual.adjudication.subscriber.id
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name

In registration-processor-default.properties, the possible Error codes are as follows:

Verification

This stage is applicable only if required biometrics are not present in the packet as per country configuration.

Sends applicant's demographic documents (via Queue + Datashare) to external Verification System (VS).
Receives decision from VS and accordingly forwards the packets.
If rejected, notifies the applicant.

Verification request to Queue is as follows:

{
  "id": "mosip.verification.adjudicate",
  "version": "1.0",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2019-02-14T12:40:59.768Z",
  "referenceId": "27847657360002520181208123456",
  "referenceURL": "<datashare url for regid>",
    "addtional": [
      {
        "abisId": "<abis app code>",
        "response": "<abis response text received>"
      }
    ]
  }
}

requestId: verification_request_id that is associated with each request present in reg_verification table.

referenceId: reg_id that is associated with each request present in reg_verification table.

referenceURL: Datashare URL of biometrics, demographics(identity) ,audits, metainfo, documents of reg_id .

Sample request

{
  "id": " mosip.verification.adjudicate ",
  "version": "1.0",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "referenceId": "10002100741000320210107125533",
  "requesttime": "2021-01-19T07:16:22.930Z",
  "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD",
  "addtional": null,
}

Sample Response

{
  "id": " mosip.verification.adjudicate ",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "responsetime": "2021-01-19T13:16:22.930Z",
  "returnValue": "1"
}

Response parameters

returnValue: 1-success, 2-failure

Datashare structure

Datashare contains biometrics, identity, documents, metainfo, audits related to particular rid and datashare URL contains encrypted form of this data.

Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.

Sample request URL

GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD

Sample Encrypted Response

Block 1:

• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.

• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

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

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

• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

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

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

Block 1:

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

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

Block 2:

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

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

Sample Response in case of Authentication Failure

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

Possible Error codes and Messages from Datashare URL

Policy structure

partner Id: mpartner-default-adjudication policy Id: mpolicy-default-adjudication

{
  "shareableAttributes": [
    {
      "attributeName": "biometrics",
      "group": "CBEFF",
      "source": [
        {
          "attribute": "registration-client/NEW/individualBiometrics",
          "filter": [
            {
              "type": "Iris"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Finger"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Face"
            }
          ]
        }
      ],
      "encrypted": true,
      "format": "extraction"
    },
    {
      "attributeName": "fullName",
      "source": [
        {
          "attribute": "fullName"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "dateOfBirth",
      "source": [
        {
          "attribute": "dateOfBirth"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "gender",
      "source": [
        {
          "attribute": "gender"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "phone",
      "source": [
        {
          "attribute": "phone"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "email",
      "source": [
        {
          "attribute": "email"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine1",
      "source": [
        {
          "attribute": "addressLine1"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine2",
      "source": [
        {
          "attribute": "addressLine2"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine3",
      "source": [
        {
          "attribute": "addressLine3"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "region",
      "source": [
        {
          "attribute": "region"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "province",
      "source": [
        {
          "attribute": "province"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "city",
      "source": [
        {
          "attribute": "city"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "postalCode",
      "source": [
        {
          "attribute": "postalCode"
        }
      ],
      "encrypted": true
    }
  ],
  "dataSharePolicies": {
    "typeOfShare": "Data Share",
    "validForInMinutes": "30",
    "transactionsAllowed": "100000",
    "encryptionType": "none",
    "shareDomain": "datashare.datashare",
    "source": "Packet Manager"
  }
}

Configuration used in Verification

registration.processor.queue.verification.request
registration.processor.queue.verification.request.messageTTL
registration.processor.verification.policy.id
registration.processor.verification.subscriber.id
activemq.message.format
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name

Error Codes

Registration Processor Developers Guide

Overview

Registration Processor(Regproc) is a backend processing engine to enable the ID Lifecycle management. It has several stages and services, registration packet flows through various stages depending on the type of flow.

The documentation here will guide you through the prerequisites required for the developer's setup.

Software setup

Below are a list of tools required in Registration Processor:

JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)

Follow the steps below to set up Registration Processor on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to conf folder C:\Program Files\apache-maven-3.8.4\conf.

3. Install Eclipse, open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update.

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

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

Code setup

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

Importing and building of a project

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

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all the config files inside sandbox-local folder except .gitignore, README and LICENSE.

4. As Registration Processor is using two properties files, registration-processor-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

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

The server should now be up and running.

8. Before running any application of Registration Processor, replace the below properties in bootstrap.properties:

spring.cloud.config.uri=http://localhost:51000/config

spring.cloud.config.label=master

spring.profiles.active=default

spring.profiles.active can be dmz or mz(default)

9. An alternative approach to start the application is to place the dependency of application to be executed in the pom of MOSIP stage executor update maven and place above mentioned properties in the bootstrap.properties and then start MOSIP stage executor.

Registration Processor Developers Guide

Overview

The documentation here will guide you through the prerequisites required for the developer's setup.

Software setup

Below are a list of tools required in Registration Processor:

JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)

Follow the steps below to set up Registration Processor on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to conf folder C:\Program Files\apache-maven-3.8.4\conf.

3. Install Eclipse, open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update.

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

Code setup

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

Importing and building of a project

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

Environment setup

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all the config files inside sandbox-local folder except .gitignore, README and LICENSE.

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

Example:

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

The server should now be up and running.

8. Before running any application of Registration Processor, replace the below properties in bootstrap.properties:

spring.cloud.config.uri=http://localhost:51000/config

spring.cloud.config.label=master

spring.profiles.active=default

spring.profiles.active can be dmz or mz(default)

Manual Adjudication and Verification

When biometric duplicates are found in ABIS, the MOSIP system sends a request for manual adjudication to the Manual Adjudication System via a queue.
The system integrator can build the Manual Adjudication System, which would be listening to the MOSIP-to-ManualAdjudication queue for any manual adjudication requests and sends a response back in the ManualAdjudication-to-MOSIP system after verifying the data.
The data sent to the Manual Adjudication System is driven by a policy defined in MOSIP and the specification is similar to ABIS identify request.

The manual adjudication stage in registration processor performs the following functions:

Sends the applicant's demographic and biometric information (via queue + Datashare) to Manual Adjudication System (MAS).
Receives decision from MAS and accordingly forwards the packets.
If rejected, notifies the applicant.

Manual Adjudication request to Queue is as follows:

{
  "id": "mosip.manual.adjudication.adjudicate",
  "version": "1.0",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2019-02-14T12:40:59.768Z",
  "referenceId": "27847657360002520181208123456",
  "referenceURL": "<datashare url for regid>",
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "27847657360002520181208123451",
        "referenceURL": "<data share for matchedRegId>"
      },
      {
        "referenceId": "27847657360002520181208123452",
        "referenceURL": "<data share for matchedRegId>"
      }
    ],
    "addtional": [
      {
        "abisId": "<abis app code>",
        "response": "<abis response text received>"
      }
    ]
  }
}

Request parameters

requestId: request_id that is associated with each request present in reg_manual_verification table.

referenceId: reg_id that is associated with each request present in reg_manual_verification table.

referenceURL: Datashare url of biometrics, demographics(identity), audits, metainfo, documents of reg_id

gallery: contains the matched ref_id and referenceURL of matched ref_id.

Sample request

{
  "id": "mosip.manual.adjudication.adjudicate",
  "version": "1.0",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "referenceId": "10002100741000320210107125533",
  "requesttime": "2021-01-19T07:16:22.930Z",
  "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD",
  "addtional": null,
  "gallery": {
    "referenceIds": [
      {
        "referenceId": "10002100741000120210107111325",
        "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202137493575474iefnvvsD"
      }
    ]
  }
}

Manual adjudication response structure from MAS

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "responsetime": "2019-02-14T12:40:59.768Z",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "27847657360002520181208123451",
        "analytics": {
          //This section is optional 
          "primaryOperatorID": "110011",
          "primaryOperatorComments": "<comments provided by operator>",
          "secondaryOperatorID": "110012",
          "secondaryOperatorComments": "<comments provided by operator>",
          "key1": "value1",
          "key2": "value2"
        }
      }   
    ],
    "analytics": {
      // This section is optional
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Response parameters

returnValue: 1-Success, 2-Failure

candidateList: It contains matched candidate referenceIds, count and analytics.

Scenario: No match

Response structure- Not Matched (No Duplicate Profile found)

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "c278b2f1-29f7-4d1a-9fa7-e93e3f932816",
  "responsetime": "2022-09-23T06:31:31.7456782+00:00",
  "returnValue": "1",
  "candidateList": {
    "count": "0",
    "candidates": [],
    "analytics": null
  }
}

Scenario: There are matches

Response structure

{
  "id": "mosip.manual.adjudication.adjudicate",
  "requestId": "58d5bb0e-e65e-4907-b452-81edbfd3ae46",
  "responsetime": "2022-09-23T06:33:11.9869624+00:00",
  "returnValue": "1",
  "candidateList": {
    "count": "1",
    "candidates": [
      {
        "referenceId": "10001100010000620220923053704",
        "analytics": {
          "primaryOperatorID": "admin",
          "primaryOperatorComments": "MATCHED",
          "Face": "F",
          "Finger": "Right_Thumb,Right_Index,Right_Middle,Right_Ring,Right_Little,Left_Thumb,Left_Index,Left_Middle,Left_Ring,Left_Little",
          "Iris": "Right_Iris,Left_Iris"
        }
      }
    ],
    "analytics": null
  }
}

Datashare structure

Datashare contains biometrics, identity documents, metainfo, audits related to particular rid and the datashare URL contains encrypted form of this data.

Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.

Sample Request URL

GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD

Sample Encrypted Response

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1:

• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.

• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

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

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

• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

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

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

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1:

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

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

Block 2:

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

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

Sample response in case of Authentication Failure

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

Possible Error Codes and messages from Datashare URL

Error Code

Error Message

Policy structure

partner Id: mpartner-default-adjudication policy Id: mpolicy-default-adjudication

{
  "shareableAttributes": [
    {
      "attributeName": "biometrics",
      "group": "CBEFF",
      "source": [
        {
          "attribute": "registration-client/NEW/individualBiometrics",
          "filter": [
            {
              "type": "Iris"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Finger"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Face"
            }
          ]
        }
      ],
      "encrypted": true,
      "format": "extraction"
    },
    {
      "attributeName": "fullName",
      "source": [
        {
          "attribute": "fullName"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "dateOfBirth",
      "source": [
        {
          "attribute": "dateOfBirth"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "gender",
      "source": [
        {
          "attribute": "gender"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "phone",
      "source": [
        {
          "attribute": "phone"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "email",
      "source": [
        {
          "attribute": "email"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine1",
      "source": [
        {
          "attribute": "addressLine1"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine2",
      "source": [
        {
          "attribute": "addressLine2"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine3",
      "source": [
        {
          "attribute": "addressLine3"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "region",
      "source": [
        {
          "attribute": "region"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "province",
      "source": [
        {
          "attribute": "province"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "city",
      "source": [
        {
          "attribute": "city"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "postalCode",
      "source": [
        {
          "attribute": "postalCode"
        }
      ],
      "encrypted": true
    }
  ],
  "dataSharePolicies": {
    "typeOfShare": "Data Share",
    "validForInMinutes": "30",
    "transactionsAllowed": "100000",
    "encryptionType": "none",
    "shareDomain": "datashare.datashare",
    "source": "Packet Manager"
  }
}

Configuration used in Manual adjudication

registration.processor.queue.manual.adjudication.request
registration.processor.queue.manual.adjudication.request.messageTTL
registration.processor.manual.adjudication.policy.id
registration.processor.manual.adjudication.subscriber.id
registration.processor.manual.adjudication.subscriber.id
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name
registration.processor.queue.manual.adjudication.request
registration.processor.queue.manual.adjudication.request.messageTTL
registration.processor.manual.adjudication.policy.id
registration.processor.manual.adjudication.subscriber.id
registration.processor.manual.adjudication.subscriber.id
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name

In registration-processor-default.properties, the possible Error codes are as follows:

Error Code

Error Message

Verification

This stage is applicable only if required biometrics are not present in the packet as per country configuration.

Sends applicant's demographic documents (via Queue + Datashare) to external Verification System (VS).
Receives decision from VS and accordingly forwards the packets.
If rejected, notifies the applicant.

Verification request to Queue is as follows:

{
  "id": "mosip.verification.adjudicate",
  "version": "1.0",
  "requestId": "987654321-89AB-CDEF-0123-456789ABCDEF",
  "requesttime": "2019-02-14T12:40:59.768Z",
  "referenceId": "27847657360002520181208123456",
  "referenceURL": "<datashare url for regid>",
    "addtional": [
      {
        "abisId": "<abis app code>",
        "response": "<abis response text received>"
      }
    ]
  }
}

requestId: verification_request_id that is associated with each request present in reg_verification table.

referenceId: reg_id that is associated with each request present in reg_verification table.

referenceURL: Datashare URL of biometrics, demographics(identity) ,audits, metainfo, documents of reg_id .

Sample request

{
  "id": " mosip.verification.adjudicate ",
  "version": "1.0",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "referenceId": "10002100741000320210107125533",
  "requesttime": "2021-01-19T07:16:22.930Z",
  "referenceURL": "http://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD",
  "addtional": null,
}

Sample Response

{
  "id": " mosip.verification.adjudicate ",
  "requestId": "4d4f27d3-ec73-41c4-a384-bf87fce4969e",
  "responsetime": "2021-01-19T13:16:22.930Z",
  "returnValue": "1"
}

Response parameters

returnValue: 1-success, 2-failure

Datashare structure

Datashare contains biometrics, identity, documents, metainfo, audits related to particular rid and datashare URL contains encrypted form of this data.

Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.

Sample request URL

GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD

Sample Encrypted Response

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1:

• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.

• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.

Block 2:

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

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

• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.

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

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

Encrypted Key Data

KEY_SPLITTER

Encrypted Actual Data

Block 1:

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

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

Block 2:

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

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

Sample Response in case of Authentication Failure

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

Possible Error codes and Messages from Datashare URL

Error Code

Error Message

Policy structure

partner Id: mpartner-default-adjudication policy Id: mpolicy-default-adjudication

{
  "shareableAttributes": [
    {
      "attributeName": "biometrics",
      "group": "CBEFF",
      "source": [
        {
          "attribute": "registration-client/NEW/individualBiometrics",
          "filter": [
            {
              "type": "Iris"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Finger"
            }
          ]
        },
        {
          "attribute": "CNIE/verification/biometrics",
          "filter": [
            {
              "type": "Face"
            }
          ]
        }
      ],
      "encrypted": true,
      "format": "extraction"
    },
    {
      "attributeName": "fullName",
      "source": [
        {
          "attribute": "fullName"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "dateOfBirth",
      "source": [
        {
          "attribute": "dateOfBirth"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "gender",
      "source": [
        {
          "attribute": "gender"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "phone",
      "source": [
        {
          "attribute": "phone"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "email",
      "source": [
        {
          "attribute": "email"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine1",
      "source": [
        {
          "attribute": "addressLine1"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine2",
      "source": [
        {
          "attribute": "addressLine2"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "addressLine3",
      "source": [
        {
          "attribute": "addressLine3"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "region",
      "source": [
        {
          "attribute": "region"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "province",
      "source": [
        {
          "attribute": "province"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "city",
      "source": [
        {
          "attribute": "city"
        }
      ],
      "encrypted": true
    },
    {
      "attributeName": "postalCode",
      "source": [
        {
          "attribute": "postalCode"
        }
      ],
      "encrypted": true
    }
  ],
  "dataSharePolicies": {
    "typeOfShare": "Data Share",
    "validForInMinutes": "30",
    "transactionsAllowed": "100000",
    "encryptionType": "none",
    "shareDomain": "datashare.datashare",
    "source": "Packet Manager"
  }
}

Configuration used in Verification

registration.processor.queue.verification.request
registration.processor.queue.verification.request.messageTTL
registration.processor.verification.policy.id
registration.processor.verification.subscriber.id
activemq.message.format
mosip.regproc.data.share.protocol
mosip.regproc.data.share.internal.domain.name

Error Codes

Error Code

Error Message