This document contains the 'Registration Client' application initial setup, update and configuration process.
Registration Client application is a desktop based application, that can be used to captures the demographic and biometric details of a resident along with supporting information (like proof documents & information about parent/guardian/introducer) and packages the information in a secure way using RSA based algorithm. The information packet can be sent to the server in an online or offline mode for processing.
The registration client application leverages the TPM capabilities and secure the data and mark the senders identity in the request before sending to external system. The MOSIP server would validate the request and make sure that the request is received from the right source. Every individual machine's TPM public key should be registered at MOSIP server to accept and process the data send by them.
A Trusted Platform Module (TPM) is a specialized chip on a local machines that stores RSA encryption keys specific to the host system for hardware authentication. Each TPM chip contains an RSA key pair called the Endorsement Key (EK). The pair is maintained inside the chip and cannot be accessed by software. By leveraging this security feature every individual machine would be uniquely registered and identified by the MOSIP server component.
OpenJDK version "11.0.8" version to build the application.
Registration Client application is built with four different modules
registration-client - it contains only UI related code.
registration-libs - it contains the code to generate the initial run.bat.
registration-MDM-service - MOSIP Device Manager service to integrate with BIO device and render the required data in a standard format and that will be consumed by the 'registration-services' module.
registration-services - it contains the Java API, which would be called from UI module to render the services to the User and capture the detail from User and store it in DB or send to external systems through services.
CPU - Dual Core Processor - 2GHZ
Ram - 16 GB
Local Storage Disk Space - 500 GB
USB 2.0 ports or equivalent hub.
Physical machine with TPM 2.0 facility.
Windows OS [10 v]
Before running the 'Registration Client' application, following prerequisites to be completed:
Before building the 'registration-services' module, all the external dependent services URLs should be configured in the 'spring.properties' and 'mosip-application.properties' files.
Property file - [spring.properties] should be updated with right environment [env] and other details.
All Master data should be loaded at MOSIP Master database.
User, machine, device & center mapping, and all other required table and data setup should exist in MOSIP Master database along with the profile and desired roles configuration in IAM server.
Below are the mandatory master data mapping that should be available in master database.
The centers and zone's should be created for the country (in registration_center & zone tables respectively).
The user id's should be mapped to a center & a zone (in the user_details & zone_user table respectively) and corresponding user credentials should be created in KeyCloak.
The registration machines should be created and mapped to a center and zone (in the machine_master tables).
The devices to be used for registration activities should be whitelisted & mapped to a center and zone (in the device_master tables).
The corresponding history details should be also be populated for centers, zones, machines, devices & zone user tables, so that the validations in registration processor do not fail.
User's machine should have online connectivity to access the client_upgrade_server, where the application binaries are available.
If TPM enabled, a logged-in user to windows machine should have permission to get the public key from TPM device.
Through the sync process, the data would be updated into the local database from the server.
All the required dependent services should be installed, up and running before running the client application.
Installation of Open Source Anti Virus Software [ClamAV]:
Download the ClamAV (Version: 0.101.2) Anti Virus Software - link.
Install the downloaded .exe file.
ClamAV Config Setup
Rename the clamd.conf.sample to clamd.conf from the installed directory of ClamAV. Ex: C:\Program Files\ClamAV\conf_examples\clamd.conf.sample file save as C:\Program Files\ClamAV\conf_examples\clamd.conf
Rename the freshclam.conf.sample to freshclam.conf from the installed directory of ClamAV. Ex: C:\Program Files\ClamAV\conf_examples\ freshclam.conf.sample file save as C:\Program Files\ClamAV\conf_examples\ freshclam.conf
Comment the line# 8(Example) in both the files
Download the Antivirus database from the following urls and placed it in the database folder(C:\Program Files\ClamAV\database)
http://database.clamav.net/main.cvd
http://database.clamav.net/daily.cvd
http://database.clamav.net/bytecode.cvd
Update Config files:
clamd.conf file changes:
Uncomment LogFile "C:\Program Files\ClamAV\clamd.log"(Line 14)
freshclam.conf file changes:
Uncomment the below mentioned lines in the file,
DatabaseDirectory - "C:\Program Files\ClamAV\database"(Line 13)
UpdateLogFile - "C:\Program Files\ClamAV\freshclam.log"(Line 17)
DatabaseMirror - db.XY.clamav.net(Line 69) change XY to our country code [Eg: IN]
DatabaseMirror - database.clamav.net(Line 75)
Checks 24(Line 113)
LocalIPAddress aaa.bbb.ccc.ddd(Line 131) change to our machine IP address
Once all the Configurations are done run the freshclam.exe and then run clamd.exe. If required, restart the machine.
Download - Application Initial Setup file
User downloads registration client zip from https:///registration-client//reg-client.zip.
Once downloaded then unzip the file into a particular location. It contains the following folder structure.
bin: It contains the client UI and service binaries in an encrypted format.
lib: It contains the library required for the application to run.
cer: It contains the certificate used to communicate with the MOSIP server.
run.bat: batch file to launch the application.
jre: It contains the java runtime engine along with the required DLLs.
Set "mosip.hostname" environment variable, with domain name being the value to be used by registration-client.
Click the 'run.bat' to initiate the setup process.
"mosip.hostname" property can also be defined in the aforementioned file spring.properties of the registration-services module.
When the user clicks on the 'run.bat' it does the following:
Communicate with client_upgrade_server through a secured connection and download the maven-metadata.xml file to identify the latest jar versions.
Compare the checksum of the local version of jar files with the data present in the Manifest.mf file.
Identify the list of binary files and Download the required jars.
Once download completed, decrypts the UI and service jars and start the application.
Application Startup
Once after application launches, TPM is initialized with RSA endorsement keys when TPM mode enabled / fallback implementation is initialzed ('reg.key', 'reg.pub', and 'readme.txt' will be created in your user.home directory with under .mosipkeys folder).
On initial startup, DB and DB pwd is autogenerated. DB password is secured using TPM key and encrypted db.conf is saved under .mosipkeys folder inside user.home directory.
Use TPM public key / from readme.txt copy the public key and machine name (hostname) and use it in machine's update API.
User should initially be online to validate their authentication against the MOSIP server. Post which, the sync process would be initiated.
Once the sync process completed then restart the application to pick the local configuration.
User should perform the self onboarding before start using the application.
The application refers to the 'maven-metadata.xml' to verifies any new version exists or not.
mosip.rollback.path - Make sure that the rollback path is provided in this variable, which is available in 'spring.properties' file; as part of the registration-services module.
During the startup of the application, the software check will be validating against the maven-metadata.xml file from client_upgrade_server. If any diffs found, the application prompts the user with 'Update Now' or 'Update Later' options to install immediately or later. Apart from this, there is another menu option available in the application to trigger the 'Update' process post login to the application. The update process would update both the application binaries and DB.
During the update process, the running application refer to the 'rollback' path and take the back up of 'lib, bin, MANIFEST.MF' files inside rollback folder with the new folder as 'Version_timstamp' format.
Download and Update the required binary libraries and DB script into the existing running folder and restart the application.
The database update can be rolled out through the binary update process. If any changes in the script then the respective script would be attached inside 'registration-service/resource/sql/version folder [like: 0.12.8]' and deliver the jar with the newer version. During the update process, the jar would be downloaded and script inside the jar would be executed. It would also contains the 'rollback' {registration-service/resource/sql/version folder_rollback [like: 0.12.8_rollback]} script if update process to be rollbacked due to any technical error.
The application provided with the facility of multiple configurations for a different set of parameters. Each attribute level configuration changes should be performed at 'Config' server and same should be sync to the local machine through kernel services. Here few of the configurations are listed out that provide the facility to enable and disable the biometric.
Refer the registration configuration maintained in Configuration Repository.
S.No.
Config Key
Sample Values
Description
1
mosip.registration.iris_threshold
0 - 100
2
mosip.registration.leftslap_fingerprint_threshold
0 - 100
3
mosip.registration.rightslap_fingerprint_threshold
0 - 100
4
mosip.registration.thumbs_fingerprint_threshold
0 - 100
5
mosip.registration.num_of_fingerprint_retries
3
6
mosip.registration.num_of_iris_retries
3
7
mosip.registration.supervisorverificationrequiredforexceptions
TRUE
To capture Supervisor approval for exception case
8
mosip.registration.gpsdistanceradiusinmeters
3
9
mosip.registration.packet.maximum.count.offline.frequency
100
No. of packets can be created in offline mode
10
mosip.registration.user_on_board_threshold_limit
1
No. of biometric required to be captured
11
mosip.registration.finger_print_score
100
12
mosip.registration.pre_reg_no_of_days_limit
5
13
mosip.registration.reg_pak_max_cnt_apprv_limit
100
Max No. of packets waiting for approval
14
mosip.registration.reg_pak_max_time_apprv_limit
30
Max time wait for approval in mins
15
mosip.registration.eod_process_config_flag
Y/N
Enable/ Disable EOD process
16
mosip.registration.invalid_login_count
3
17
mosip.registration.invalid_login_time
2
18
mosip.registration.gps_device_enable_flag
Y/N
Enable / Disable GPS
19
mosip.registration.uin_update_config_flag
Y/N
Enable / Disable update feature
20
mosip.registration.lost_uin_disable_flag
Y/N
Enable / Disable Lost UIN functionality
21
mosip.registration.webcam_name
logitech
22
mosip.registration.document_scanner_enabled
Y/N
23
mosip.registration.onboarduser_ida_auth
Y/N
To enable the bio auth validation during user 'On Boarding' process and validated against the IDA Auth service
Refer the global configuration maintained in Configuration Repository environment.
S.No.
Config Key
Sample Values
Description
1
mosip.primary-language
fra / ara/ eng
French/ Arabic/ English
2
mosip.secondary-language
fra / ara/ eng
French/ Arabic/ English
To enable or disable the TPM functionality, modify the mentioned key in 'registrtaion-libs/props/mosip-application.properties' file.
mosip.reg.client.tpm.availability = { Y - to enable the TPM, N - to disable the TPM}
It integrates the Registration application with biometric devices (Iris/ Fingerprint/ Face).
S.No.
Config Key
Sample Values and Description
1
mosip.registration.mdm.default.portRangeFrom=4501
To run the MDM service in local machine's port
2
mosip.registration.mdm.default.portRangeTo=4600
To run the MDM service in local machine's port
Registration client verifies the below-configured URL to check whether the system is in online or not. The application uses this URL to perform the health check before communicating with the external services.
S.No.
Config Key
Sample Values and Description
1
mosip.reg.healthcheck.url={URL}
Ex: https//://domainname.com/v1/authmanager/actuator/health
Property attributes and the respective sample values are provided below. Before building the registration-services, the required below properties needs to be changed.
File Location: /registration-libs/src/main/resources/props/mosip-application.properties
mosip.reg.client.url={Reg client download url from client_upgrade_server }
mosip.reg.logpath=../logs
mosip.reg.packetstorepath={where the registration packet should be stored}.
mosip.reg.healthcheck.url={Application uses this url to perform the health check before communicating with the external services. Default value: https://${environment}/v1/authmanager/actuator/health}
mosip.reg.rollback.path={where the application backup should be taken during software update} [Default: ../BackUp]
mosip.reg.cerpath=/cer//mosip_cer.cer
mosip.reg.xml.file.url={client_upgrade_server url with maven-metadata.xml file}
mosip.reg.app.key={contains the key to be used to decrypt the application binaries during run time}
mosip.reg.client.tpm.availability={ Y - to enable the TPM, N - to disable the TPM, default N}
In Registration client application, only user mapping to the local machine can be performed. Rest of the data setup should be performed at MOSIP Admin portal. Through sync process the data would be sync between local machine and server based on machine's public key and center id. There are other services that are available to send the created packet from local machine to remote system.
S.No.
Service Name
Service Description
Module Name
1
User Detail Sync
To synchronize the user related information. Without this sync user can't login to the application.
Kernel
2
User Salt Sync
User's password is validated using this salt. Without this sync user can't login to the app.
Kernel
3
Master Data Sync
Reg. client application related master data are sync from server using this sync. Without this sync, the app won't work.
Kernel
4
Application configuration Sync
Reg. client app related dynamic configuration parameters are sync from server. Without this sync, the app won't work.
Kernel
5
Policy Sync
Sync the key required for packet creation based on center and machine id. Packet can't be created without this sync.
Kernel
6
MOSIP public key Sync
To synchronize the MOSIP public key, which is used during response sign validation.
Kernel
7
Pre-registration Data Sync
To download the center specific pre-registration packet data based on date range.
Pre-Registration
8
Packet Sync
To upload the list of packet related information before uploading actual packet. Without this sync, the packet can't be uploaded to the server .
Registration-Processor
9
Packet Status reader
At regular interval read the status of the uploaded packet and update the same in local db.
Registration-Processor
10
Packet Upload
To upload the packet generated out of New/ Lost UIN / Update UIN process to MOSIP server.
Registration-Processor
11
Send OTP
To send OTP message to the user's mobile no. during authentication process.
Kernel
12
Auth Service - UserName and Password
To get the auth token based on user provided user name and password. This token would be attached in the request while making any service calls in the same user context.
Kernel
13
Auth Service - UserName and OTP
To get the auth token based on user provided user name and OTP.
Kernel
14
Auth Service - Client id and Secret Key
To get the auth token based on client id and secret key.
Kernel
15
Validate / Invalidate auth Token
To validate and invalidate the generated token.
Kernel
16
ID-Authentication API
To on board the user based on user's bio authentication. Without this service, user on-borading screen won't work if bio auth enabled.
ID-Authentication
This section covers the list of drivers required to communicate with the external devices.
To integrate with Scanner, windows WIA libraries are used. So, the respective service should be running and also the scanner specific driver should also be installed.
The application has been currently tested with CANON LiDE 120.
Printer should be available to take the print out from application and the respective driver should be installed.
Camera and the respective driver should be available to capture the applicant photo. Application tested with Logitech camera.
When there is an integrated camera associated with the machine, it needs to be disabled.
If GPS enabled through configuration then the respective device/ model specific driver should be installed to communicate through application.