EIDA ID Card Toolkit v2.3.0

chainbirdinhandSecurity

Feb 23, 2014 (3 years and 4 months ago)

270 views



EIDA
ID Card
Toolkit

v
2
.
3.0

Remote Secure Messaging
Service
-

Interface
Specifications

V 0.
2


Security Classification:

INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
2

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future


Document Details

Organization

Emirates Identity Authority (EIDA)

Document Title

Document
Name

Date

30
-
11
-
2011

Doc Name / Ref

Remote Secure Messag
ing Service
-

Interface Specifications

Classification


Document Type




INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
3

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future


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 S
ession Keys

................................
................................
...............

13

6.

MOC data preparation

................................
................................
..........................

13

7.

MOC Build SM Command

................................
................................
.....................

14


Abbreviations

Abbreviation

Description

API

Application Programming Interface

SM

Secure messaging



INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
4

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

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
T
oolkit 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
S
M

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:



T
ransport protocol




M
essage
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 state
d

in
this document
are
appli
cable

for the both
Remote SM
service

implementations
implemented in
JAVA and .NET.


The document is organi
s
ed
as below
:

-

Section 2
:
O
verview
on the
Remote SM service

a
rchitecture.

-

Section 3:
I
nterface specifications

-

Section
4
:
Ca
lling sequences for
Remote SM service

functions

-

Section 5: Message Specifications




INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
5

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

2

Remote SM service

A
rchitecture

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 co
mponent:

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 base
d 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.


INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
6

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

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 bu
t 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 obj
ect 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
.


INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
7

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

4


Message
Specifications


EIDA toolkit
Remote SM service

is implemented as an HTTP responder that relives
client application from dealing with comple
x 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 (JSO
N 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 specifications for the
request
\
response of the remo
te SM service functions.

4.1

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”

q桥

A捴i潮 fil敤 捯ct慩n猠t桥 湡me
of t桥 f畮捴i潮 to 扥 i湶潫敤


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 executi
on 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 t
o “
bfaA qo潬kit
qro畢l敳e潯ting g畩摥
” for error description


Sample
Response
JSON Object

{"result":"srezRvooJBQ="}

INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
8

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future


4.2

GenerateC
ipheredPIN


Request

To invoke this function the host application shall send the below JSON object as the
value of the HTTP re
quest parameter “Message”
:

JSON Field Name

Value

Action


d敮er慴敃i灨敲敤ein


C慲摃ry灴潧p慭

ㄲ 批t敳⁃erd Cry灴pgram i渠扡獥s㐠f潲m慴

䍓C

㠠批t敳⁣er搠獥ri慬 湵mb敲ei渠扡獥n4 f潲m慴


Sample
Request JSON Object

{"Action":"GenerateCipheredPIN","CardCryp
togram":"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 str
eam, 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 “
bfaA
q潯lkit qr潵扬敳e潯tin朠g畩摥
” for error description



Sample
Response JSON Object

{"result":"agiyC1Nt6VpDSg=="}





INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
9

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

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

A
ction


jlCj畴畡uA畴桥湴楣uti潮


䍓C

㠠批t敳⁣er搠獥ri慬 湵mb敲ei渠扡獥n4 f潲m慴

okafCC

㠠批t敳⁣er搠捨慬l敮g攠楮 扡獥s㐠f潲m慴

pkfCC

㠠批t敳⁍lC 獥物sl 湵m扥r i渠扡獥n4 f潲m慴


Sample
Request JSON Object

{"Action":"MocMutualAuthentication","CSN":"AsA
Aw+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 res
ponse 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

bfaA q潯lkit qr潵扬敳e潯ti湧 g畩摥
” for error

摥獣si灴楯渠


Sample
Response JSON Object

{"result":"C8dj0mM2hWdRD0o/55Ud4yMfDGIonVDnQcFQ6wKW7+3II
Ml/hJ90fvkrH5O9v9OptVajT6ojplLyGAZ1hlFIDDt6rFZAnzAh"}





INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
10

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

4.4

MOCGenerateSessionKeys


Request

To invoke this function the host application shall send the bel
ow JSON object as the
value of the HTTP request parameter “Message”
:

JSON Field Name

Value

Action


j潣䝥湥牡o敓敳獩潮h敹s


C慲摃ry灴潧p慭

㜲 批t敳et桡t 慲a t桥 捡c搠捲y灴pgam i渠n 扡猶s f潲oat.


Sample
Request JSON Object

{"Action":"MocGenerateSessionKe
ys","CardCryptogram":"7CyJxGEYaBZON8uV21
594VcEa24zjj2ZbtycRpHpbXIQFULSR66fnB0rkj4l9pYyxOM2faQWKSGzl2yQxxsw
RELVwy42KzYE"}

Response

The remote SM service executes the function came in “Action” field then constructs
JSON object containing the execution resul
ts 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


单䍃䕓p
” if the function successes otherwise error
code returned, please refer to “
bfaA 呯o
lkit
qro畢l敳e潯ting g畩摥
” for error description


Sample
Response JSON Object

{"result":"SUCCESS"}




INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
11

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

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


j潣o畩l摓jC潭o慮d


Amar彃潭o慮d

㐠批t敳⁷桡t 慲a t桥 m慴捨
J

J
捡r搠䅐ar
.

Amar彄慴a

finger灲楮t tem灬慴攠
t桡t i猠灲数慲敤pfor mat捨c潮 捡牤
f畮捴i潮

pj彃潭o慮摟C慳a

Number “3” (fixed value)


Sample
Request
JSON

Object

{"Action":"MocBuildSMCommand","SM_Command_Case":"3","APDU_Data":"Xy6Bk
DjRAFJIAVxVAlppAxv0A2CQEAtwEFmXEhRfElt6E1eKFCVMFh1IF1C2F0llF1zFG
W3fGjZHG1fzHUxSHlRcHka6IjPsIzbXJTrMJhrcJyfHKgm6KhzFKkOzLBmlLiaqL2qS
L2OhMByRMHOCMRR1MW2nMkKtMjqTMjCAM3qIM0GdMyZzM2D
KNkVtOEXBO
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 “
bfaA q潯lkit 呲潵ql敳e潯ting g畩摥

f潲 敲r潲 摥獣sipt
i潮




Sample
Response JSON Object

{"result":"DCAAAY6Bgl8ugX5R5AM99AU88AYntQcvZQ81UhAkVhBq2yISgSNrxSN
uuSRb8yRC2SVQzSURnCUxySYhxiYYtCc5rigbmShQuChauCgVeSk3oiosjCshgSs
qfSxGlyxxoyxUnC0day1IhC4tci8YYy85aTBjgjBwmzBKZTFsizFYcDFqXTdtvj6OCE5
vmPhzO41D"}

INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
12

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

5

C
a
lling 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
-
of
f
-
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
evok
es
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 su
ccessfully 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 w
ith cardholder fingerprint.

INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
13

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

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 Mes
saging

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 cal
ls 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 ho
st 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 t
he 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 docu
mentation.

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”.



INTERNAL


Chainbirdinhand_18b49
d27
-
Fe41
-
4d10
-
935c
-
Bcc9d73f872a.Doc






Page
1
4

of
14





لـضفا لـبقتسم لـجا نم ... ةـينطو ةـيؤر

National

Vision … For Better Future

7.

MOC Build SM Command

The host application evokes this function to acquire the ma
tch=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.