Security Classification:
EIDA ID Card Toolkit
v2.3.0
Remote Secure Messaging
Service - Interface
Specifications V 0.2
INTERNAL
Document Details
Organization
Emirates Identity Authority (EIDA)
Document Title
Document Name
Date
30-11-2011
Doc Name / Ref
Remote Secure Messaging Service - Interface Specifications
Classification
Document Type
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 2 of 14
INTERNAL
Contents
1
Introduction ....................................................................................................................... 4
2
Remote SM service Architecture ....................................................................................... 5
3
Interface Specifications ..................................................................................................... 6
4
Message Specifications .................................................................................................... 7
4.1
GenerateChallenge ................................................................................................. 7
4.2
GenerateCipheredPIN ............................................................................................ 8
4.3
MOCMutualAuthentication ...................................................................................... 9
4.4
MOCGenerateSessionKeys .................................................................................. 10
4.5
MocBuildSMCommand ......................................................................................... 11
5
Calling sequence .............................................................................................................12
5.1
Is Card Genuine .................................................................................................... 12
1.
Generate SM Challenge ....................................................................................... 12
2.
Generate Ciphered PIN ........................................................................................ 12
5.2
Biometric Authentication (Match-off-card) ............................................................. 12
5.3
Biometric Authentication (Match-on-card) ............................................................. 13
1.
Get MOC Serial Number ....................................................................................... 13
2.
Get MOC Challenge.............................................................................................. 13
3.
SM MOC Mutual Authentication ............................................................................ 13
4.
MOC Mutual Authentication .................................................................................. 13
5.
MOC Generate Session Keys ............................................................................... 13
6.
MOC data preparation .......................................................................................... 13
7.
MOC Build SM Command ..................................................................................... 14
Abbreviations
Abbreviation
Description
API
Application Programming Interface
SM
Secure messaging
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 3 of 14
INTERNAL
1 Introduction
EIDA toolkit Remote SM service is a server side component works over HTTP(s) protocol to
offer remote access to EIDA SM modules (SAM, HSM or SOFT HSM (only for test cards))
for EIDA Toolkit client components such as toolkit web components (for web applications )or
toolkit APIs (for desktop applications). The web service is required in case of using some of
the card functions that requires either SM or cryptography authentication in order to read
sensitive data from the card.
This document is intended to describe Remote SM service architecture and the service
interface specifications including:

Transport protocol

Message format and structure
The document also describes the sequence in which the service functions shall be
consumed to conduct the below functions:

Is Card Genuine

Biometric verification (Match-off-card)

Biometric verification (Match-on-card)
NOTE: all the specifications stated in this document are applicable for the both Remote SM
service implementations implemented in JAVA and .NET.
The document is organised as below:
-
Section 2: Overview on the Remote SM service architecture.
-
Section 3: Interface specifications
-
Section 4: Calling sequences for Remote SM service functions
-
Section 5: Message Specifications
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 4 of 14
INTERNAL
2 Remote SM service Architecture
The below figure shows the Remote SM service components in server side and client side,
how server component is being consumed by the web service client that is part from the
toolkit APIs and how a business application can consume the service functions via the toolkit
APIs.
Web Service Architecture
As shown above, the web service architecture comprises the following components:

Server component: a java servlet or .NET http responder that listens to the client
calls then communicates to EIDA SM module (SAM or HSM) in order to process
those calls

Client component: the web service is utilized through EIDA toolkit APIs or web
components based on the business application architecture. In both cases a
dedicated module called “web service client” is actually communicating with the web
service, please refer to the “EIDA_Toolkit_Developer's_Guide” document for more
details about the API functions that are using the remote SM service.
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 5 of 14
INTERNAL
3 Interface Specifications

Transport medium: HTTP or HTTPS, HTTP verb: “POST”

Message format: TEXT

Message structure: JavaScript Object Notation (JSON) object sent as value of
an HTTP request parameter called “Message”.
JSON is a lightweight data-interchange format. It is easy for humans to read and
write. It is easy for applications to parse. It is based on a subset of the JavaScript
Programming Language.
JSON is a text format that is completely language independent but uses
conventions that are familiar to programmers of the C-family of languages, including
C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties
make JSON an ideal data-interchange language.
JSON object is an unordered set of name/value pairs. An object begins with { (left
brace) and ends with } (right brace). Each name is followed by : (colon) and the
name/value pairs are separated by , (comma).
Example of JSON Object:
{"Action":"GenerateChallenge"}
The bove example shows JSON object with one field named “Action”, and the
value assigned to this field is “GenerateChallenge”.

Session maintenance: The remote SM service is state-full where the data
related to a sequence is maintained in user web-session, the web session ID is
returned to the calling application as cookie, therefore the HTTP response
returned from the service will contain the header “Set-Cookie” and hence the
calling application (whether it is desktop or web component) shall parse the
cookies returned in the “Set-Cookie” header then pass it back to the remote SM
service through the Cookie Container of the next HTTP request.
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 6 of 14
INTERNAL
4
Message Specifications
EIDA toolkit Remote SM service is implemented as an HTTP responder that relives
client application from dealing with complex message formats and complex
protocols.
A client application can invoke a function in the Remote SM service using the HTTP
verb “POST” that is natively supported in all programming languages.
As mentioned above the remote SM service expects a message (JSON object) as
HTTP request parameter called “Message”. The host application specifies the name
of the function to be invoked in the JSON object field “Action”.
The below sub-sections states the JSON object
request\response of the remote SM service functions.
4.1
specifications
for
the
GenerateChallenge
Request
To invoke this function the host application shall send the below JSON object as the
value of the HTTP request parameter “Message”:
JSON Field Name
Value
Description
Action
“GenerateChallenge”
The Action filed contains the name
of the function to be invoked
Sample Request JSON Object
{"Action":"GenerateChallenge"}
Response
The remote SM service executes the function which came in “Action” field then
constructs JSON object containing the execution results and finally writes the JSON
object directly to the HTTP response stream, the below table describe the response
JSON object:
JSON Field Name
Value
Result
8 bytes challenge in a bas64 format or error code in
case of failure, please refer
to “EIDA Toolkit
Troubleshooting guide” for error description
Sample Response JSON Object
{"result":"srezRvooJBQ="}
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 7 of 14
INTERNAL
4.2
GenerateCipheredPIN
Request
To invoke this function the host application shall send the below JSON object as the
value of the HTTP request parameter “Message”:
JSON Field Name
Value
Action
“GenerateCipheredPin”
CardCryptogram
12 bytes Card Cryptogram in base64 format
CSN
8 bytes card serial number in base64 format
Sample Request JSON Object
{"Action":"GenerateCipheredPIN","CardCryptogram":"NAeeFCjBEnqIN43+","CSN":"
AsAAw+AqBm4="}
Response
The remote SM service executes the function came in “Action” field then constructs
JSON object containing the execution results and finally writes the JSON object
directly to the HTTP response stream, the below table describe the response JSON
object:
JSON Field Name
Value
Result
10 bytes that are the Ciphered PIN in a bas64 format
or error code in case of failure, please refer to “EIDA
Toolkit Troubleshooting guide” for error description
Sample Response JSON Object
{"result":"agiyC1Nt6VpDSg=="}
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 8 of 14
INTERNAL
4.3
MOCMutualAuthentication
Request
To invoke this function the host application shall send the below JSON object as the
value of the HTTP request parameter “Message”:
JSON Field Name
Value
Action
“MOCMutualAuthentication”
CSN
8 bytes card serial number in base64 format
RNDICC
8 bytes card challenge in base64 format
SNICC
8 bytes MOC serial number in base64 format
Sample Request JSON Object
{"Action":"MocMutualAuthentication","CSN":"AsAAw+AqBm4=","RNDICC":"fHWRm
v+3wKM=","SNICC":"AgFpAQ4VII0="}
Response
The remote SM service executes the function came in “Action” field then constructs
JSON object containing the execution results and finally writes the JSON object
directly to the HTTP response stream, the below table describe the response JSON
object:
JSON Field Name
Value
Result
72 bytes that are the server cryptogam in a bas64
format or error code in case of failure, please refer to
“EIDA Toolkit Troubleshooting guide” for error
description
Sample Response JSON Object
{"result":"C8dj0mM2hWdRD0o/55Ud4yMfDGIonVDnQcFQ6wKW7+3II
Ml/hJ90fvkrH5O9v9OptVajT6ojplLyGAZ1hlFIDDt6rFZAnzAh"}
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 9 of 14
INTERNAL
4.4
MOCGenerateSessionKeys
Request
To invoke this function the host application shall send the below JSON object as the
value of the HTTP request parameter “Message”:
JSON Field Name
Value
Action
“MocGenerateSessionKeys”
CardCryptogram
72 bytes that are the card cryptogam in a bas64 format.
Sample Request JSON Object
{"Action":"MocGenerateSessionKeys","CardCryptogram":"7CyJxGEYaBZON8uV21
594VcEa24zjj2ZbtycRpHpbXIQFULSR66fnB0rkj4l9pYyxOM2faQWKSGzl2yQxxsw
RELVwy42KzYE"}
Response
The remote SM service executes the function came in “Action” field then constructs
JSON object containing the execution results and finally writes the JSON object
directly to the HTTP response stream, the below table describe the response JSON
object:
JSON Field Name
Value
Result
“SUCCESS” if the function successes otherwise error
code returned, please refer
to “EIDA Toolkit
Troubleshooting guide” for error description
Sample Response JSON Object
{"result":"SUCCESS"}
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 10 of 14
INTERNAL
4.5
MocBuildSMCommand
Request
To invoke this function the host application shall send the below JSON object as the
value of the HTTP request parameter “Message”:
JSON Field Name
Value
Action
“MocBuildSMCommand”
APDU_Command
4 bytes what are the match-on-card APDU.
APDU_Data
fingerprint template that is prepared for match on card
function
SM_Command_Case
Number “3” (fixed value)
Sample Request JSON Object
{"Action":"MocBuildSMCommand","SM_Command_Case":"3","APDU_Data":"Xy6Bk
DjRAFJIAVxVAlppAxv0A2CQEAtwEFmXEhRfElt6E1eKFCVMFh1IF1C2F0llF1zFG
W3fGjZHG1fzHUxSHlRcHka6IjPsIzbXJTrMJhrcJyfHKgm6KhzFKkOzLBmlLiaqL2qS
L2OhMByRMHOCMRR1MW2nMkKtMjqTMjCAM3qIM0GdMyZzM2DKNkVtOEXBO
HbiOQ==","APDU_Command":"DCAAAQ=="}
Response
The remote SM service executes the function came in “Action” field then constructs
JSON object containing the execution results and finally writes the JSON object
directly to the HTTP response stream, the below table describe the response JSON
object:
JSON Field Name
Value
Result
Match on card command in base64 format if the
function success , otherwise error code returned,
please refer to “EIDA Toolkit Troubleshooting guide”
for error description
Sample Response JSON Object
{"result":"DCAAAY6Bgl8ugX5R5AM99AU88AYntQcvZQ81UhAkVhBq2yISgSNrxSN
uuSRb8yRC2SVQzSURnCUxySYhxiYYtCc5rigbmShQuChauCgVeSk3oiosjCshgSs
qfSxGlyxxoyxUnC0day1IhC4tci8YYy85aTBjgjBwmzBKZTFsizFYcDFqXTdtvj6OCE5
vmPhzO41D"}
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 11 of 14
INTERNAL
5 Calling sequence
This section specifies the sequence in which the Remote SM service function shall
be invoked in order to conduct the cryptographic processes that are pre-requisites
to the below functions :
 Is Card Genuine
 Biometric Authentication (Match-off-card)
 Biometric Authentication (Match-on-card)
5.1
Is Card Genuine
The function “Is Card Genuine” conducts a process where the SM module generates
a ciphered PIN that is being verified by the ID Applet on EIDA card, the role of the
Remote SM service in this case it to generate the ciphered PIN using EIDA remote
SM module to verified by the card later on.
Here is the sequence in which Remote SM service functions shall be invoked to
acquire the Ciphered PIN.
1. Generate SM Challenge
The host application evokes this function to generate a random challenge from the
SM module and cashes into the user session to be used later, the function returns
the challenge to the client for reference only, i.e. client doesn’t need to do anything
with the returned client.
2. Generate Ciphered PIN
The host application evokes this function after “Generate SM Challenge”, in order to
generate and return the Ciphered PIN the calling application where the PIN is sent to
the card for verification.
If the Ciphered PIN was verified successfully by the card then the card genuine UAE
card.
5.2
Biometric Authentication (Match-off-card)
The Match-off-card function requires reading the fingerprints stored on the card then
does the matching operation with the cardholder fingerprint outside the card.
The host application must be authenticated to the card so that the card allows
reading the fingerprints stored on it.
The card authenticates the host application when it successfully verifies the Ciphered
PIN and hence the same sequence specified in section 5 shall be followed to acquire
the same PIN and then the host application sends that PIN to the card for verification.
Once the Ciphered PIN is verified successfully, the application can read the
fingerprints from the card then off-card matching with cardholder fingerprint.
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 12 of 14
INTERNAL
5.3
Biometric Authentication (Match-on-card)
Matching the fingerprints inside the card (that is known as match-on-card) enforces
establishing SM with the card then sends the matching command to the card over
SM.
Establish Secure Messaging
In order to establish SM with card, the host application call the below functions with
specified sequence (functions marked in grey are executed on the card so it is out if
this document scope, however it is only stated for sequence clarification):
1. Get MOC Serial Number
The host application calls this function to retrieve the match on card (MOC)
applet’s serial number to be sent as a parameter to the Remote SM service
function “MOC Mutual Authentication”.
2. Get MOC Challenge
The host application calls this function to retrieve a random challenge from
the card (generated from the match on card (MOC) applet); this challenge will
be sent as a parameter to the Remote SM service function “MOC Mutual
Authentication”.
3. SM MOC Mutual Authentication
The host application evokes this function to acquire the server Cryptogram.
4. MOC Mutual Authentication
The host application sends the server cryptogram to this function for
verification and to acquire the Card Cryptogram that will be sent as a
parameter to the Remote SM service function “MOC Generate Session Keys”.
5. MOC Generate Session Keys
The host application evokes this function to instruct the remote SM module to
generate session key in order to start the SM session.
Execute Match-on-card
6. MOC data preparation
When the cardholder fingerprint , it is then converted to a ISO template using
the toolkit convert function, however this template has to be further
normalized to match the fingerprint templates stored on the card as specified
in the card documentation.
The host application shall send the match-on-card APDU command along
with the normalized as parameters to the Remote SM service function “MOC
Build SM Command”.
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 13 of 14
INTERNAL
7. MOC Build SM Command
The host application evokes this function to acquire the match=on-card
command encoded in SM mode, the host application sends the command to
the card where the fingerprint matching is conducted and the result returned.
‫ من اجـل مستقبـل افضـل‬... ‫رؤيـة وطنيـة‬
National Vision … For Better Future
533560581
Page 14 of 14