RD Client Integration Document

CURRENT VERSION DETAIL

Project Name Windows RD service Solution

Project Version 2.0.1.11

Prepared By Date Prepared

Manish Pandey
23rd August 2017
Approved By Date Approved

Udita Singh
23rd August 2017
Comments

References

Classification: Restricted Page 1 of 16

 RD Client Integration Document

DOCUMENT VERSION HISTORY

DOC Date Date Date
Description of Changes Prepared By Reviewed By Approved By
Ver. Prepared Reviewed Approved
23 May
1.0 1st Beta release Tanuj Joshi Udita Singh
2017
24 May
1.1 1st Beta release Tanuj Joshi Udita Singh 24-May-17 Udita Singh 24-May-17
2017
Input and output data details
1.2 Udita Singh 30-May-17 Udita Singh 30-May-17 Udita Singh 30-May-17
added
Integration with Mozilla Abhishek 12 June 12 June 12 June
1.3 Udita Singh Udita Singh
Firefox and Google Chrome Gupta 2017 2017 2017
This release is tested 4th July 4th July
1.5 Manish Pandey Udita Singh 4th July 2017 Udita Singh
successfully on Chrome Only 2017 2017
This release is tested 5th July 5th July
1.6 Manish Pandey Udita Singh 5th July 2017 Udita Singh
successfully on Chrome Only 2017 2017
This release is tested Abhishek 13th July th
13 July 13th July
1.7 Udita Singh Udita Singh
successfully on Chrome Only Gupta 2017 2017 2017
This release is tested Abhishek 22nd July 22nd July 22nd July
1.8 Udita Singh Udita Singh
successfully on Chrome Only Gupta 2017 2017 2017
This release is tested 31st July 31st July 31st July
1.9 Manish Pandey Udita Singh Udita Singh
successfully on IE 2017 2017 2017
White listed functionality has
4th Aug 4th Aug 4th Aug
1.10 been added. Manish Pandey Udita Singh Udita Singh
2017 2017 2017
Increase Response Timeout
1.11 Added Trouble shoot Manish Pandey 17-Aug-17 Udita Singh 17-Aug-17 Udita Singh 17-Aug-17
1. Proxy Configuration
has been added.
2. Device Serial Number
field has been added
in Device Info
Response.
3. Qscore field has
been added in
Capture Response.
4. Functionalities have
been added includes Manish 23rd Aug 23rd Aug 23rd Aug
1.12 Udita Singh Udita Singh
– Otp+Bio, Pandey 2017 2017 2017
OTp+Demo,
OTp(Proto and XML).
5. More logs have been
added in Rd Service.
6. nmpoints field has
been added for the
possible combination
of Biometric capture.

Classification: Restricted Page 2 of 16

 RD Client Integration Document

Table of Contents
1. Introduction ............................................................................................................................ 4
2. Scope ....................................................................................................................................... 4
3. Installation Steps of RD service ............................................................................................... 4
4. Un-Installation Steps ............................................................................................................... 4
5. Registration steps of Biometric Device ................................................................................... 4
6. Pre-Requisites for Https Communication from Web Browser after Installation ................ 5
7. Configuration settings according to environment .................................................................. 6
7.1 Staging : ............................................................................................................................. 6
7.2 Preproduction : ................................................................................................................. 6
7.3 Production :....................................................................................................................... 7
8. RD Services API Calling ............................................................................................................ 7
8.1 RDSERVICE......................................................................................................................... 7
8.2 DEVICEINFO ....................................................................................................................... 8
8.3 CAPTURE ......................................................................................................................... 10
9. Error Codes from RD service ................................................................................................. 13
10. Troubleshooting ................................................................................................................. 13
11. S/W and H/W Requirements for new release ................................................................... 16

Classification: Restricted Page 3 of 16

 RD Client Integration Document

1. Introduction

Purpose of this document is to help the developers to integrate the Windows RD service in their
application.

2. Scope

Scope of this document is limited to the Windows RD, its installation, integration with the Client
application.

3. Installation Steps of RD service

1. Run 'MorphoRdServiceL0SoftSetup.exe' as administrator to install the

RD Service

2. Follow the instruction in setup wizard to complete the installation.

4. Un-Installation Steps

1. Run 'C:\MorphoRdServiceL0SoftSetup\unins000.exe' to uninstall the

RD Service OR Uninstall “Morpho RD Service Version Driver” from Control Panel.

2. Follow the instruction in setup wizard to complete the installation.

5. Registration steps of Biometric Device

1. Plug-in the Morpho Biometric Device.

2. If the Morpho Biometric Device is white listed in Management Server, it will be

registered without giving Activation Code manually, but if it is not then user will
be prompted an Activation Code Window to enter Activation Code for
registration.

[Activation Code will be shared by Smart Chip Pvt Ltd]

Classification: Restricted Page 4 of 16

 RD Client Integration Document

6. Pre-Requisites for Https Communication from Web Browser after

Installation

1) Set value 'CommunicationMode:0' in 'C:\MorphoRdServiceL0Soft\ConfigSettings.ini'

file to enable Https communication in Morpho RD Service.

2) Keep the Bank/Merchant's server certificate file at 'C:\MorphoRdServiceL0Soft\'

named as 'server.crt'. Certificate must be in pem format.

3) Keep the Bank/Merchant's server private key file at 'C:\MorphoRdServiceL0Soft\'

named as 'server.key'. Private key must be in pem format.

4) Rename '127.0.0.1' as Bank/Merchant's URL to which certificate is issued, in the host

file of the windows present at 'C:\Windows\System32\drivers\etc'. Update this URL in
the calling JavaScript functions given in the MorphoRDServiceTestPage.html.

5) Restart the Morpho RD Service.

Please note:
The server.crt is a CA signed certificate, in case of integration it can be a self signed
certificate. But to avoid any browser issue please use signed certificate.
To generate a self signed certificate please follow the below link:

https://www.ibm.com/support/knowledgecenter/en/SSWHYP_4.0.0/com.ibm.apimgmt.
cmc.doc/task_apionprem_gernerate_self_signed_openSSL.html

or

https://jamielinux.com/docs/openssl-certificate-authority/

Classification: Restricted Page 5 of 16

 RD Client Integration Document

7. Configuration settings according to environment

7.1 Staging :

1. Change the RDEnviroment variable in ConfigSetting.ini file (file PATH :

C:\MorphoRdServiceL0Soft\).
RDEnviroment:0

2. Change the URLs:

Registration : https://Stage-rdm.smartbioplus.com/rdm-device-app/registration
Keyrotation : https://Stage-rdm.smartbioplus.com/rdm-key-management-app/keyRotation
Telemetry : https://Stage-rdm.smartbioplus.com/rdm-telemetry-app/telemetry

3. Change Domain : Stage-rdm.smartbioplus.com

4. Change URL_Port: 443

5. Save the changes in config file.
6. Restart the service to effect the changes.

---------------------------------------------------------------------

7.2 Preproduction :

1. Change the RDEnviroment variable ConfigSetting.ini file (file PATH :

C:\MorphoRdServiceL0Soft\).
RDEnviroment:1

2. Change the URLs:

Registration : https://pre-rdm.smartbioplus.com/rdm-device-app/registration
Keyrotation : https://pre-rdm.smartbioplus.com/rdm-key-management-app/keyRotation
Telemetry : https://pre-rdm.smartbioplus.com/rdm-telemetry-app/telemetry

3. Change Domain: pre-rdm.smartbioplus.com

4. Change URL_Port: 443

5. Save the changes in config file.
6. Restart the service to effect the changes.

Classification: Restricted Page 6 of 16

 RD Client Integration Document

7.3 Production :

1. Change the RDEnviroment variable ConfigSetting.ini file (file PATH :

C:\MorphoRdServiceL0Soft\).
RDEnviroment:2

2. Change the URLs:

Registration : https://rdm.smartbioplus.com/rdm-device-app/registration
Keyrotation : https://rdm.smartbioplus.com/rdm-key-management-app/keyRotation
Telemetry : https://rdm.smartbioplus.com/rdm-telemetry-app/telemetry

3. Change Domain : rdm.smartbioplus.com

4. Change URL_Port: 443

5. Save the changes in config file.
6. Restart the service to effect the changes.

8. RD Services API Calling

There are 3 actions in MorphoRDServiceTestPage.html, these actions are listed below:
a. RDSERVICE
b. DeviceInfo
c. Capture

The sequence of calling the API is as follows:

1. RDSERVICE->DeviceInfo
2. RDSERVICE->Capture

8.1 RDSERVICE

To discover RD Service, please use the below Javascript code snippet:

Function
RDService()
{
var url = "http://127.0.0.1:11100";

var xhr;
var ua = window.navigator.userAgent;
var msie = ua.indexOf("MSIE ");

Classification: Restricted Page 7 of 16

 RD Client Integration Document

if (msie > 0 || !!navigator.userAgent.match(/Trident.*rv\:11\./)) // If Internet

Explorer, return version number
{
//IE browser
xhr = new ActiveXObject("Microsoft.XMLHTTP");
} else {
//other browser
xhr = new XMLHttpRequest();
}
xhr.open('RDSERVICE', url, true);
xhr.onreadystatechange = function () {

if (xhr.readyState == 4){
var status = xhr.status;
if (status == 200) {
alert(xhr.responseText);
console.log(xhr.response);
} else {
console.log(xhr.response);
}
}
};
/*setTimeout(function(){
xhr.send();},1000);*/
xhr.send();
}

8.2 DEVICEINFO
To get device info, please use the below Javascript code snippet:

function
DeviceInfo()
{
var url = "http://127.0.0.1:11100/getDeviceInfo";

var xhr;

Classification: Restricted Page 8 of 16

 RD Client Integration Document

var ua = window.navigator.userAgent;
var msie = ua.indexOf("MSIE ");
if (msie > 0 || !!navigator.userAgent.match(/Trident.*rv\:11\./)) // If Internet
Explorer, return version number
{
//IE browser
xhr = new ActiveXObject("Microsoft.XMLHTTP");
} else {
//other browser
xhr = new XMLHttpRequest();
}
xhr.open('DEVICEINFO', url, true);
xhr.onreadystatechange = function () {

if (xhr.readyState == 4){
var status = xhr.status;
if (status == 200) {
alert(xhr.responseText);
console.log(xhr.response);
} else {
console.log(xhr.response);
}
}
};
xhr.send();
}
Response data:
<DeviceInfo dpId="" rdsId="" rdsVer="" dc="" mi="" mc="" >
<additional_info><Param name=”serial_number” value=”"/></additional_info></DeviceInfo>

dpId – (mandatory) Unique code assigned to registered device provider.

rdsId – (mandatory) Unique ID of the certified registered device service.
rdsVer – (mandatory) Registered devices service version.
dc – (mandatory) Unique Registered device code.
mi – (mandatory) Registered device model ID.

Classification: Restricted Page 9 of 16

 RD Client Integration Document
mc – (mandatory) This attribute holds registered device public key
certificate. This is signed with device provider key.
In additional info tag, value field is the device serial number connected.

8.3 CAPTURE
To use CAPTURE command, please use the below Javascript code snippet:
function
{
Capture()
var url = "http://127.0.0.1:11100/capture";
var PIDOPTS='<PidOptions ver=\"1.0\">'+'<Opts fCount=\"1\" fType=\"0\"
iCount=\"\" iType=\"\" pCount=\"\" pType=\"\" format=\"0\" pidVer=\"2.0\"
timeout=\"10000\" otp=\"\" wadh=\"\" posh=\"\"/>'+'</PidOptions>';
/*
format=\"0\" --> XML
format=\"1\" --> Protobuf
*/
var xhr;
var ua = window.navigator.userAgent;
var msie = ua.indexOf("MSIE ");
if (msie > 0 || !!navigator.userAgent.match(/Trident.*rv\:11\./)) // If Internet
Explorer, return version number
{
//IE browser
xhr = new ActiveXObject("Microsoft.XMLHTTP");
} else {
//other browser
xhr = new XMLHttpRequest();
}
xhr.open('CAPTURE', url, true);
xhr.setRequestHeader("Content-Type","text/xml");
xhr.setRequestHeader("Accept","text/xml");
xhr.onreadystatechange = function () {

if (xhr.readyState == 4){
var status = xhr.status;
if (status == 200) {

Classification: Restricted Page 10 of 16

 RD Client Integration Document

alert(xhr.responseText);

} else {
console.log(xhr.response);
}
}
};
xhr.send(PIDOPTS);
}

Input data detail need to send in the above request:

<PidOptions ver="">
<Opts fCount="" fType="" iCount="" iType="" pCount="" pType="" format="" pidVer="" timeout="" otp=""
wadh="" posh=""/>
<Demo></Demo>
<CustOpts>
<!-- no application should hard code these and should be configured on app or AUA servers. These
parameters can be used for any custom application authentication or for other configuration parameters.
Device providers can differentiate their service in the market by enabling advanced algorithms that
applications can take advantage of. -->
<Param name="" value="" />
</CustOpts>
</PidOptions>
It should send this input data in this key “PID_OPTIONS” using intent to RD Service
Where:
PidOptions:
ver: Version of the PidOtopns spec. Currently it is “1.0”. This is necessary to allow applications to
gracefully upgrade even when RD service may be been upgraded. RD Service must support current
version and one previous version to allow apps to upgrade at different points in time.
Opts:
Int fCount (optional) number of finger records to be captured (0 to 10)
Int fType (optional) ISO format (0 for FMR or 1 for FIR), 0 (FMR) is default
iCount (optional) number of iris records to be captured (0 to 2)
Int iType (optional) ISO format (0 for IIR), 0 (IIR) is default
Int pCount (optional) number of face photo records to be captured (0 to 1).
Currently face matching is not supported.
Int pType (optional) face format. Currently face matching is not supported.
Int format (mandatory) 0 for XML, 1 for Protobuf
String pidVer (mandatory) PID version
Int timeout capture timeout in milliseconds
String otp (optional) OTP value captured from user in case of 2-factor auth
String wadh (optional) If passed, RD Service should use this within PID block root element “as-is”.

Classification: Restricted Page 11 of 16

 RD Client Integration Document

String posh (optional) if specific positions need to be captured, applications can pass a comma delimited
position attributes. See “posh” attribute definition in Authentication Specification for valid values. RD
Service (if showing preview) can indicate the finger using this. If passed, this should be passed back within
PID block. Default is “UNKNOWN”, meaning “any” finger/iris can be captured.
Demo:
Element allows demographic data to be passed to form PID block as per authentication
specification

Response Data Format:

When it request to capture finger data using RD Service, It returns some xml data as output
that would be further used to Authentication as well as eKYC.
<PidData>
<Resp errCode="" errInfo="" fCount="" fType="" iCount="" iType="" pCount="" pType="" nmPoints=""
qScore=""/>
<DeviceInfo />
<Skey ci="">encrypted and encoded session key</Skey>
<Hmac>SHA-256 Hash of Pid block, encrypted and then encoded</Hmac>
<Data type="X|P"> base-64 encoded encrypted pid block </pid>
</PidData>
Where:
Resp:
Int errCode (mandatory) 0 if no error, else standard error codes
String errInfo (optional) additional info message in case of error/warning
Int fCount (mandatory for FP) number of finger records actually captured
Int fType (mandatory for FP) actual format type – 0 (FMR) or 1 (FIR)
Int iCount (mandatory for Iris) number of iris records actually captured
Int iType (mandatory for Iris) actual Iris format (0 for IIR)
Int pCount (mandatory for Photo) number of face photo records actually captured. Currently face
matching is not supported.
Int pType (mandatory for Photo) face format. Currently face matching is not supported.
Int nmPoints (mandatory for FMR capture) Number of minutiae points when FMR is captured.
Applications may use this for accepting or retrying the capture. If multiple fingers are captured, send
comma delimited numbers.
Int qScore (optional) If quality check is done, send a normalized score that is between 0 and 100. Device
providers may allow configuration within RD service to use specific quality check algorithms to be
enabled. Either it can be configured within RD service or applications can pass those under
PidOptions CustOpts Param.
Skey:
String skey (mandatory) encrypted session key as per auth spec
String ci (mandatory) UIDAI public key identifier as per auth spec
Hmac:
String hmac (mandatory) hmac value as per auth spec.

Classification: Restricted Page 12 of 16

 RD Client Integration Document

9. Error Codes from RD service

100 “Invalid PidOptions input. XML should strictly adhere to spec.”

110 “Invalid value for fType”
120 “Invalid value for fCount”
130 “Invalid value for iType”
140 “Invalid value for iCount”
150 “Invalid value for pidVer”
160 “Invalid value for timeout”
170 “Invalid value for posh”
180 “Face matching is not supported”
190 “Invalid value for format”
200 “Invalid Demo structure”
210 "Protobuf format not supported"
700 “Capture timed out”
710 “Being used by another application”
720 “Device not ready”
730 “Capture Failed”
740 “Device needs to be re-initialized”
750 "RD Service does not support fingerprints"
760 "RD Service does not support Iris"
770 "Invalid URL"
999 “Internal error”

10. Troubleshooting

S.No. Error Code Error Info Occurrence Solution

1. 100 Invalid PidOptions When RD Service calling Before calling capture
input. XML should application sends corrupt function check pidoption xml
strictly adhere to spec. pidoption xml or may be format properly.
incomplete pid option xml.
2. 110 Invalid value for fType When RD Service calling Before calling capture
application sends wrong function check fType
value for finger type attribute value properly. It
according to UIDAI should be according to UIDAI
registered device registered device document.
document.
3. 120 Invalid value for fCount When RD Service calling Before calling capture
application sends wrong function check fCount
value for finger count attribute value properly. It
according to UIDAI should be according to UIDAI
registered device registered device document.
document.

Classification: Restricted Page 13 of 16

 RD Client Integration Document

4. 130 Invalid value for iType When RD Service calling Before calling capture
application sends wrong function check iType attribute
value for iris type according value properly. It should be
to UIDAI registered device according to UIDAI registered
document. device document.
5. 140 Invalid value for iCount When RD Service calling Before calling capture
application sends wrong function check iCount
value for iris count attribute value properly. It
according to UIDAI should be according to UIDAI
registered device registered device document.
document.
6. 150 Invalid value for pidVer When RD Service calling Before calling capture
application sends wrong function check pidVer
value for pidblock version attribute value properly. It
according to UIDAI should be according to UIDAI
registered device registered device document.
document.
7. 160 Invalid value for timeout When RD Service calling Before calling capture
application sends wrong function check timeout
value for timeout according attribute value properly. It
to UIDAI registered device should be according to UIDAI
document. registered device document.
8. 170 Invalid value for posh When RD Service calling Before calling capture
application sends wrong function check posh attribute
value for posh according to value properly. It should be
UIDAI registered device according to UIDAI registered
document. device document.
9. 180 Face matching is not When RD Service calling Morpho RD Service not
supported application sends value for supported face matching. So
pCount and pType. ignore/remove pCount and
pType attributes.

10. 190 Invalid value for format When RD Service calling Before calling capture
application sends wrong function check format
value for format according attribute value properly. It
to UIDAI registered device should be according to UIDAI
document. registered device document.
11. 200 Invalid Demo structure When RD Service calling Before calling capture
application sends wrong function check Demo xml
Demo xml format according format attribute value
to UIDAI Aadhaar properly. It should be
authentication document. according to UIDAI Aadhaar
authentication document.

Classification: Restricted Page 14 of 16

 RD Client Integration Document

11. 700 Capture timed out. If Customer not putting Make sure customer put their
finger on sensor within finger on sensor within giving
giving timeout. timeout.
12. 710 Being used by another If Fingerprint sensor busy Make sure fingerprint sensor
application. by another application should be in ready state. So
call device info and check rd
service status before calling
capture. If RD Service status is
ready than capture should be
perform.

13. 710 Being used by another If Fingerprint sensor busy Make sure fingerprint sensor
application. by another application should be in ready state. So
call device info and check rd
service status before calling
capture. If RD Service status is
ready than capture should be
perform.

14. 720 Device not ready. If Fingerprint device haven’t Make sure fingerprint sensor
permission. has permission and USB cable
connection should be perfect.
During capture usb
connection loose.

Backward compatible issue

15. 730 Capture Failed Some unknown issue Retry process

16. 740 Device needs to be re- When RD Service Do Registration

initialized environment changed
17. 760 RD Service does not When RD Service calling Morpho RD Service not
support Iris application sends value for supported eye matching. So
iCount and iType. ignore/remove iCount and
iType attributes.

18. 999 Internal error Problem Occur during Retry Capture

PID generation Retry Capture
During Finger Capture Launch RD Service and
RD Service in different click refresh button at
Environment right top corner.
Device date time is not Please ensure that value
set to automatic. of env attribute in PID
Internal error Option xml is

Classification: Restricted Page 15 of 16

 RD Client Integration Document

correct(according to RD
Service environment).
Host Machine date &
time should be auto sync.
Please ensure that value
of env attribute in PID
Option xml is
correct(according to RD
Service environment).

11. S/W and H/W Requirements for new release

Prerequisites for S/W

OS - Windows 7
Web Browser - Chrome version 59.0.3071.115 and IE 11

Prerequisites for H/W

Morpho MSO1300 E, MSO1300 E2, MSO1300 E3 Biometric Sensor

Any other tool

NA

Classification: Restricted Page 16 of 16