EIDA ID Card Toolkit v2.7

fortunabrontideInternet and Web Development

Nov 13, 2013 (3 years and 11 months ago)

2,725 views



EIDA ID Card Toolkit

v
2.
7

Developer’s Guide


p散erity Cl慳獩fi捡ti潮W

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
2

of
140





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

National

Vision … For Better Future


Document Details

Organization

Emirates Identity Authority (EIDA)

Document Title

EIDA ID Card Toolkit

developers guide for Java and .NET
developers

Date

31
-
10
-
201
2

Doc Name / Ref


Classification


Document Type



Document History

Date

Version

Author

Comments

15
-
8
-
2010

0.1



18
-
8
-
2010

0.2



19
-
8
-
2010

1.0



5
-
12
-
2010

2.1



2
-
8
-
2011

2.2



5
-
11
-
2011

2.2.2
v0.90


Revised the contents

15
-
11
-
2011

2.2.2
v0.91


Reviewed and made the document user
friendly.


16
-
11
-
2011

2.2.2
v0.92


Final review

10
-
01
-
2012

V 2.3


Update for Version 2.3

21
-
02
-
2012

V 2.3


Updat
e

to reflect the amendments to Web
components

21
-
03
-
2012

0.1 for
Toolkit 2.4


Released as

part of Toolkit 2.4

10
-
04
-
2012

V 2.4


Final review.

2
-
5
-
2012

V 2.5


Released as part of Toolkit 2.5

27
-
05
-
2012

V 2.6


Released as part of Toolkit 2.6 to cover
additional containers and update modifiable
data

29
-
10
-
2012

V 2.7


Released as part of Toolk
it 2.7 to cover
Zero footprint web components and ID Box
one MRZ scanner integration



INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
3

of
140





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

National

Vision … For Better Future

Contents


Contents

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

3

Table of Figures

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

6

1

Introduction

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

8

2

Compatibility

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

9

3

Installation of Toolkit

................................
................................
................................
........
10

3.1

Toolkit Components

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

10

4

Development environment

................................
................................
...............................
13

4.1

Developing
Java based application using Eclipse

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

13

4.2

Developing .NET based application using Microsoft Visual Studio

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

15

5

EIDA ID Card To
olkit functions

................................
................................
.........................
18

5.1

Establishing and Closing Context

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

18

5.2

Discovering, Connecting and Disconnecting Readers

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

19

5.3

Load SM Configuration

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

20

5.4

Establishing connection with the card

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

21

5.
5

Reading Card Related Information

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

22

5.6

Reading Card Holder Public Data

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

24

5.7

Reading Card Holder Public Data Extended

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

26

5.8

Read Public Data Contactless (MRZ Fields are entered manually)

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

27

5.9

Read Public Data Contactless (with MRZ Reader)

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

29

5.10

Reading Family Book Data

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

31

5.11

Checking Card Genuine

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

33

5.11.1

V
erifying Card Genuine in local mode

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

33

5.11.2

Verifying Card Genuine in remote mode

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

34

5.11.3

Verifying Card Genuine Extended

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

35

5.12

Matching Off/On Card

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

36

5.12.1

Reading Biometric Information Templates (BITs)

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

36

5.12.2

Capturing Fingerprints

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

37

5.12.3

Converting Fingerprint

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

40

5.12.3.1

Reading Fingerprint templates
from Card (Match
-
Off only)

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

41

5.12.3.2

Using EIDA SM module in local mode
................................
................................
...

41

5.12.3.3

Using EIDA SM module in remote mode

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

42

5.12.4

Off Card matching

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

43

5.12.5

On Card matching

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

44

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
4

of
140





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

National

Vision … For Better Future

5.13

Signing

Data with the Authentication Key

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

45

5.14

Signing Data with the Signing Key

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

46

5.15

Reading PKI certificates

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

46

5.16

PIN management functions

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

47

5.16.1

Resetting PIN

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

47

5.16.2

Changing PIN

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

47

5.17

MIFARE Emulation

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

48

5.17.1

Switch to MIFARE emulation

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

48

5.
17.2

Is Mifare Emulation Active

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

49

5.17.3

Load Key

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

49

5.17.4

Read Binary Data

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

50

5.17.5

Update Binary Data

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

51

5.18

Additional Containers

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

52

5.18.1

Labour

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

53

5.18.1.1

Create Key

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

53

5.18.1.2

Create PIN

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

54

5.18.1.3

Create Data File

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

55

5.18.1.4

Freeze Access Conditions

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

56

5.18.1.5

Update Binary

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

57

5.18.1.6

Read Binary

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

58

5.18.2

Health and Insurance

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

59

5.18.2.1

Create Key

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

60

5.18.2.2

Cr
eate PIN

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

61

5.18.2.3

Create Data File

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

62

5.18.2.4

Freeze Access Conditions

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

63

5.18.2.5

Update Binary

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

64

5.18.2.6

Read Binary

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

65

5.18.3

Defence

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

66

5.18.3.1

Create Key

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

66

5.18.3.2

Create PIN

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

67

5.18.3.3

Create Data File

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

68

5.18.3.4

Freeze Access Conditions

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

70

5.18.3.5

Update Binary

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

71

5.18.3.6

Read Binary

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

72

5.18.4

Driving License

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

73

5.18.4.1

Create Key

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

73

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
5

of
140





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

National

Vision … For Better Future

5.18.4.2

Create PIN

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

74

5.18.4.3

Create Data File

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

75

5.18.4.4

Freeze Access Conditions

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

76

5.
18.4.5

Update Binary

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

77

5.18.4.6

Read Binary

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

79

5.18.5

Qualification

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

80

5.18.5.1

Create Key

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

80

5.18.5.2

Create PIN

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

81

5.18.5.3

Create Data File

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

82

5.18.5.4

Freeze Access Conditions

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

83

5.18.5.5

Update Binary

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

84

5.18.5.6

Read Binary

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

86

5.18.6

Social Services

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

87

5.18.6.1

Create Key

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

87

5.18.6.2

Create PIN

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

88

5.18.6.3

Create Data File

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

89

5.18.6.4

Freeze Access Conditions

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

90

5.18.6.5

Upd
ate Binary

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

91

5.18.6.6

Read Binary

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

93

5.19

Update Modifiable Data

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

94

5.19.1

Update Modifiable Public Data

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

94

5.19.2

Update Address Data

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

95

5.19.3

Update Family Book Data

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

96

6

Toolkit Web
-
Components

................................
................................
................................
.
98

6.1

Steps to embed EIDA IDCard Applet on a web page

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

100

6.2

Steps to embed the Public Data ActiveX on a web page

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

100

6.3

Embedding the Digital Signature ActiveX on a web page

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

101

6.4

Referencing Toolkit Web Component (Applet or ActiveX)

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

101

6.5

Communication with the Web page

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

102

6.5.1

Initialize

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

102

6.5.2

Initialize contactless reader

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

102

6.5.3

Reading the public data

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

102

6.5.4

Reading public data Extended

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

105

6.5.5

Read Public Data Contactless (MRZ Fields are entered manually)

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

110

6.5.6

Read Publ
ic Data Contactless (with MRZ Reader)

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

110

6.5.7

Checking Card Genuine

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

111

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
6

of
140





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

National

Vision … For Better Future

6.5.8

Biometric functions

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

111

6.5.8.1

GetNumberOfAvailableFingerprints

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

111

6.5.8.2

GetFingerIndex

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

111

6.5.8.3

Capture
Image

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

112

6.5.8.4

ConvertImage

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

112

6.5.8.5

CaptureAndConvert

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

112

6.5.8.6

MatchOffCard

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

112

6.5.9

PKI Functions

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

113

6.5.9.1

SignData

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

113

6.5.9.2

Authenticate

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

113

6.5.9.3

AuthenticateWithPinCached

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

113

6.5.9.4

ReadSignCertificate

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

113

6.5.9.5

ReadAuthCertificate

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

113

6.6

Toolkit Web components JavaScript functions

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

114

7

Tool
kit Zero footprint Web
-
Components

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

115

7.1

Steps to embed EIDA IDCard Zero footprint Applet on a web page

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

115

7.2

Steps to embed
the Zero Footprint ActiveX on a web page

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

116

7.3

Communication with the Web page

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

116

7.3.1

Initialize

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

116

7.3.2

Reading the public data

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

117

7.3.3

PKI Functions

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

118

7.3.3.1

Sign Data

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

118

7.3.3.2

Sign Challenge

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

118

7.3.3.3

GetSignCertificate

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

118

7.3.3.4

GetA
uthCertificate
................................
................................
...............................

118

7.3.4

Samples

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

118

Appendix A


Secure Messaging configuration file (sm.cfg)

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

120

Appendix B


Toolkit Business Sequences

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

122

Appendix C


Fingerprint Sensor Interface Specifications

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

129

Appendix D


Switch To Mifare Emulation

Interface Specifications

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

132

Appendix E


Public Data Parser

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

134

Appendix F


ID Box One MRZ scanner

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

140



Table of Figures

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
7

of
140





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

National

Vision … For Better Future

Figure 1

Read Public Data

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

122

Figure 2

Check Card Genu
ine (Local)

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

124

Figure 3

Check Card Genuine(Remote)

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

125

Figure 4

Match off Card

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

126





Definiti
ons

Abbreviation

Description

API

Application Programming Interface


BIT

Biometric Information Template

DLL

Dynamic Link Library

EIDA

Emirates Identity Authority

HSM

Hardware Security Module

PIN

Personal Identification Number

SAM

Security Access Module

SDK

Software Development Kit

SM

Secure Messaging

VB

Visual Basic



INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
8

of
140





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

National

Vision … For Better Future

1

Introduction

This document is intended as a guide for deve
lopers who can

build
business
applications
using the
EIDA ID Card Toolkit

SDK

which provides platform to

access set of UAE ID Card
functions and features.
.

The SDK provides Java and
.NET
interfaces for developing applications thus allowing
organisations to create applications using C++, C#
,

VB and Java
programming languages
.

Detailed descriptions of the I
D Card Toolkit functions are explained in section 5 and 6 of this
document along with examples.

Note: This document is intended for Java and C# application developers. There is a
separate developer

s guide available for C++ application developers.

Import
ant pre
-
requisite
s
:

1)

Development experience in J
ava, C# and/or C++, and some specificity of the
languages
is

mandatory to
develop applications using UAE ID Card Toolkit SDK.

2)

Knowledge and experience in smart card field is necessary.

3)

Users should receive re
quired training from EIDA


INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
9

of
140





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

National

Vision … For Better Future

2

Compatibility

EIDA ID Card Toolkit

SDK is built
around a C++ core library designed to run on
Windows
Operating Systems
.
The current version of the Toolkit is designed to work on the below

o
perating Systems / programming languages
.

Platforms
: (Win32

/
Win64
)



Windows XP




Windows Vista




Windows 2003 Server




Windows 2008 Server




Windows 7

Programming languages



C/
C++



Java



.
Ne
t languages (VB, C#, …)

IDE and C
ompiler
s
:



Microsoft Visual Studio 2005 (Or Express Edition)



Microsoft Visual
Studio 2008 (Or Express Edition)



Eclipse 3.x

Java

JDK 1
.6

or higher

.Net Framework

.Net Framework 3.5 or higher

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
10

of
140





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

National

Vision … For Better Future

3

Installation

of Toolkit


Before starting the development,

EIDA ID Card Toolkit

SDK
must

be installed.

Refer

to

EIDA ID Card Toolkit

Install
atio
n

and Configuration Guid
e


d
ocument for the installation
,

prerequisites

and installation

steps
.

3.1

Toolkit
Components

The Toolkit setup

will
automatically
copy
some or all of
the below components

based on the
options chosen
.
The below table provides the list
of
co
m
ponent

names, physical
file
name

(if
applicable)
, and their
high
-
level

description

that are part of the
EIDA ID Card Toolkit

package
.

These components will be referred in the later part of this document
.

Component
Name

Physical file

Description

Cor
e Dlls

UAE_IDCardLib.dll

Core components of the
Toolkit
.

Wrappers
,
helper Dlls


Java API

UAE_IDCardJavaAPI.jar

Java API and core Dll wrapper
library
.

Secure
Messaging API

SecureMessagingAPI.jar

Used with java API for local and
remote secure messaging
.

Public Data
Parser

PublicDataParser.jar

Public data files parser and
signature validator

ID Box One
MRZ scanner
API

IDBoxMrz.jar

Interface with ID Box One MRZ
scanner

.NET API

UAE_IDCardCSharpAPI.dll


UAE_IDCardCSharpWrapper.dll

.NET wrapper for the C
ore Dll
.

Public Data
Parser

PublicDataParser.dll

Public data files parser and
signature validator

ID Box One
MRZ scanner
API

IDBoxMrz.dll

Interface with ID Box One MRZ
scanner

Web
Components


DigitalSignatureActiveX.dll

An Activex exposes all PKI functi
ons
for web based applications
.


PublicDataActiveX.dll

An
A
ctivex exposes all other
Toolkit

functions for web based
applications
.


INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
11

of
140





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

National

Vision … For Better Future

EIDA_IDCard_Applet.jar

A java Applet exposes all
Toolkit

functions for web based
applications
.


Zero footprint
web c
omponents

EIDA_ZF_ActiveX.CAB

A zero footprint ActiveX component
that has no client dependencies. It
does

does not
require
T
oolkit to be
installed, and used to read public
data raw files, data signing, and
certificate exporting

ZFApplet.jar

A zero footpr
int Java Applet
component that has no client
dependencies. It does

not

require
T
oolkit to be installed, and
it can be
used to read public data raw files,
data signing, and certificate
exporting

Sample Desktop
Application

Java

Java Sample Application
and

b
atch
file to launch the Java Sample
Application.

dotNet

.Net Sample Application

Console

Sample C++ console application to
demonstrate Toolkit kernel
functions
.

sm.cfg

Secure Messaging configuration file.

Sample Web
Components


Public Data ActiveX

a
nd
Digital
Signature ActiveX

folders

These folders

contain sample

HTML
files with the ActiveX embedded

in it
,
and also javascript

helper

files.

IDCard Applet

folder

This folder contains a sample HTML
file with the Java Applet embedded,
and also a helper
javascript files.

Web Services

Java

T
his folder contains java base
d

secure messaging web service
. It is
a
java servlet

which

provides a
remote access to SM modules (SAM
or HSM)
.

dotNet

T
his folder contains the .NET based
secure messaging web service
.
It

is
an
ASPX application
which
provides
a remote access to SM modules
INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
12

of
140





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

National

Vision … For Better Future

(SAM or HSM)
.

Website

Java

ZFDemoSite.war contains website
implemented in JSP and Servlets to
demonstrate Zero footprint web
components and complementary
server side components
.

.Net

ZFDemoSite contains website
implemented in ASP.NET to
demonstrate Zero footprint web
components and complementary
server side components
.



INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
13

of
140





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

National

Vision … For Better Future

4

D
evelopment
e
nvironment

Developers can use either

Eclipse
or
Microsoft Visual Studio

development

tools
.

This secti
on
provides
detailed steps
on how to create a new project
(application) in Eclipse and Visual
Studio.

Note: Prior to setting up the development environment,
based on the target application
platform either 32 bit or 64 bit version of
EIDA ID Card Toolkit

mu
st be installed.

4.1

Developing Java based applicatio
n

using Eclipse

Install the Eclipse development tool from the below website:


http://www.eclipse.org/downloads

After successful installation o
f Eclipse tool, follow the below steps to create a new project to
develop an application using ID Toolkit.

Refer to the screen snapshots for assistance.

a)

Run eclipse.exe

b)

Select a workspace

c)

Go to File
-
> New
-
> Java Project

d)

Enter a project name

e)

Make sure to

select JRE 6 (x86)

or (x64)











f)

Click Finish

g)

Make sure a new project is created

h)

Select the created project in package explorer



Note: If you are working on an existing project
,
go to

point i

directly
.

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
14

of
140





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

National

Vision … For Better Future

i)

Go to Project
-
> Properties

j)

Select Java
Build Path

k)

Go to Libraries Tab

l)

Click “Add External JARs” button











m)

Navigate to the path where Toolkit SDK is installed

n)

Open “API” folder

o)

Open “Java API” folder

p)

Select “UAE_IDCardJavaAPI.jar” file











INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
15

of
140





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

National

Vision … For Better Future


q)

Click “Open” button

r)

Click “Ok” button












Repeat the previous steps to add “SecureMessagingAPI.jar” if secure messaging is needed
in your application
.

Refer to the section 5 for various functions available in the Toolkit to build your application
and a
lternatively

you may use the sample

applications to familiarise yourself before starting
the development of your own.

4.2

Developing
.NET

based application using
Microsoft Visual Studio

Install the Microsoft Visual Studio 2005 or later.

Follow the below steps to create a new project to develop
an application using ID Toolkit.

Refer to the sample screen snapshots for assistance.

a)

Run Microsoft Visual Studio

b)

Go to File
-
> New
-
> Project

c)

Enter a project name

d)

Select Visual C# as a project type

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
16

of
140





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

National

Vision … For Better Future











e)

Make sure

.NET Framework 3.5 is selected

f)

Selec
t the project in project explorer

g)

Go to Project
-
> Properties

h)

Go to “Build” Tab

i)

Select “All Configurations” From “Configuration” list

j)

Then select “x86”
or “x64”
from “Platform target” list

k)

Save the changes











l)

Go to Project
-
> Add Reference…

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
17

of
140





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

National

Vision … For Better Future

m)

Go to “
Browse” tab

n)

Navigate to the path where Toolkit SDK is installed

o)

Open “API” folder

p)

Open “CSharp API” folder

q)

Select “UAE_IDCardCSharpAPI.dll” and “UAE_IDCardCSharpWrapper.dll”

r)

Click “Ok”










Refer to the section 5 for various functions available in the

Toolkit to build your application
and alternatively you may use the sample applications to familiarise yourself before starting
the development of your own.


INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
18

of
140





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

National

Vision … For Better Future

5

EIDA
ID
Card
Toolkit
f
unctions

This section
list
s the

standard
functions that are
exposed
by the
EIDA ID Toolkit API for
developing EIDA ID card based applications
.

Related functions are grouped and explained in
the sub
-
sections of this chapter

with example code (C# and Java)
.

Note for
Java Developers:

For detailed list of Classes / Functions that ar
e available in the
Toolkit, please refer to the Java Docs html pack.

Note for
.NET Developers:

For detailed list of Classes / Functions that are available in the
Toolkit, please refer to the .Net
help
pack.

Also developers are advised to refer to Appen
dix B

which describes the sequence of API
calls a developer needs to undertake to access to the main business functions of the Toolkit.

5.1

Establishing and Closing Context

In order to support a wide range of smart card readers,
EIDA ID Card Toolkit

uses the
P
C
/
SC standard to communicate with any
PC/SC compatible
smart card reader
s

and hence
PC
/
SC context must be established
first
before using any other functions of ID Card Toolkit
.
The
context
is initialized by calling the method
establishContext
().


Before cl
osing the application, i
t is important to
invoke
closeContext
()

which will

Close the
context,
relea
se the resources and clear the memory.

Note:
An application should
invoke the functions
establishContext
() and
closeContext
()

only
once.


B
elow
examples

sho
ws how to
o
pen

and
close context
in Java and C# respectively.

Java Example




C#
Example

import

emiratesid.ae.*;

import

emiratesid.ae.readersmgt
.*;


//

... Some code here ...

try

{


ReaderManagement readerMgr
=
new

ReaderManagement();


readerMgr.establishContext();


// do ID Card Operations


// ……


readerMgr.closeContext();


}
catch

(MiddlewareException ex) {



ex.printStackTrace();


}


INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
19

of
140





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

National

Vision … For Better Future


5.2

Disc
ov
ering, Connecting and Disconnecting Readers

Once a context is established,

invoking
discoverReaders
() fu
nction
will
discover all the
PC
/
SC readers connected to the local machine
.
An a
pplication can then use any of the
available
readers

to access the card functions

In case of multiple readers connected to the machine, a specific reader can be selected from
t
he list of d
iscovered r
eaders by name, or by type, or by index
, etc..
.

ReaderManagement

class
provides the below functions for selecting readers.



SelectReaderBy
Name

This function selects a specific reader with the given name.



SelectReaderByATR

This functio
n selects the first available reader that has ID card with the given ATR



SelectTestIDCardReader

This function selects the first available reader with Test ID card inserted

in the
reader
.

Card is identified by its ATR; the
T
oolkit is configured with a list

of
possible
EIDA
Test card ATRs. Please refer to the sm.CFG configuration file in
Appendix A

for
configuration details
.



SelectIDCardReader

This function selects the first available reader with Live ID card inserted.



Card is identified by its ATR; the too
lkit is configured with a list of
possible
EIDA Live
card ATRs. Please refer to the sm.CFG configuration file in
Appendix A

for
configuration details
.
SelectIDCardContactlessReader

This function selects the first available contactless reader with Live ID ca
rd
in range
.

using

EmiratesId.AE;

using

EmiratesId.AE.ReadersMgt;

//... Some code here

...

try


{


ReaderManagement

readerMgr =
new

ReaderManagement
();


readerMgr.EstablishContext();


// ... do some ID Card operations ...


readerMgr.CloseContext();


}


catch

(
MiddlewareException

ex)


{


//… handle exception here …


}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
20

of
140





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

National

Vision … For Better Future

Card is identified by its ATR; the toolkit is configured with a list of
possible
EIDA
Live card ATRs. Please refer to the sm.CFG configuration file in
Appendix A

for
configuration details
.



Note
: if any of the select functions above didn’t f
ind a reader with the required criteria
it returns a null PCSCReader object.

The b
elow examples provide the usage of
those
functions in Java and C# respectively.

Java Example


C# Example



5.3

Load

SM
Con
figuration

In order to use EIDA secure messaging in local mode, the function
IDCardWrapper.LoadConfiguration

shall be called to load

the secure messaging modules
configurations from the sm.cfg file
.

Sample
configur
ation of

i
s described in appendix
A.

The
below examples provide the usage of those functions in Java and C# respectively.

Java Example


C# Example


readerMgr.DiscoverReaders();

PCSCReader
[] readers = readerMgr.readers;

// select a reader by name code goes here

// ...

PCSCReader

selectedReader =
readerMgr.SelectReaderByName
(selectedReaderName);

//Other select methods may be called...

selectedReader.IsConnected();

bool

isUAE =
ATRSetting
.Is_UAE_Card(selectedReader.ATR);

rea
derMgr
.discoverReaders();

PCSCReader[] readers =
readerMgr
.getReaders();

// select a reader by name code goes here

// ...

PCSCReader selectedReader =
readerMgr
.selectReaderByName(selectedReaderName);

//Other select methods may be called...

selectedReader.i
sConnected();

boolean

isUAE = ATRSetting.Is_UAE_Card(selectedReader.getATR());

IDCardWrapper
.LoadConfiguration();

UAEIDCardLibJavaWrapper
.
LoadConfiguration();

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
21

of
140





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

National

Vision … For Better Future

5.4

Establish
ing

c
onnection with the card

Scenario 1:

If the
EIDA ID
card was inserted before s
electing the reader then the
T
oolkit will
automatically establish the connection with the card and hence the reader will be in
a
connected state (the function IsConnected
will

retu
r
n
TRUE

if the ID card was inserted
already
)
.

Scenario 2
:

If the EIDA ID car
d was not inserted before selecting the reader, then t
he
Connect
function
must be called to establish the connection with card whenever the card is
inserted
, the Connect function takes the
Context

parameter

as input.

Note that

the PC
/
SC context

was opened

before using the
ReaderManagement
class
, the
value of this parameter can be acquired from the property “
Context
” available in the
ReaderManagement
class
.


Tip
:

The function Connect can be used to detect the card insertion
, where Connect function
is cal
led then
IsConnected

function should be called to detect if the card is connected.

With Contactless readers support for V2 cards, there is a need to differentiate between
contactless and normal PCSC reader, therefore the function IsContactless() exists in
PCSC
reader class.

Below examples, provide the usage of the
above
functions in Java and C# respectively.


Java Example


C# Example



PCSCReader

selectedReader =
readerMgr.SelectReaderByName(selectedReaderName);

selectedReader.IsConnected();

bool

IsCardConnected =
selectedReader.
I
sConnected();

bool

isCon
tactless;

if
(isCardConnected)


isContactless

=
selectedReader
.IsContactless();


if
(!IsCardConnected)

//use the context opened before using the
ReaderManagement

object

selectedReader.
Connect(
readerMgr.

Context
);


PCSCReader selectedReade
r =
readerMgr
.selectReaderByName(selectedReaderName);

boolean

isCardConnected =
selectedReader.isConnected();

boolean

isContactless;

if
(isCardConnected)


isContactless

=
selectedReader
.isContactless();


if
(!isCardConnected)


//use the context opened befo
re using the
ReaderManagement

object


selectedReader.
Connect(
readerMgr.

Context
);

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
22

of
140





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

National

Vision … For Better Future

5.5

Reading Card Related Information

Once PCSCReader object is acquire
d in a CONNECTED state and with right type,
application can

extract the
EIDA ID
C
ard related information such as Card Serial Number,
and Chip Serial Number.

The

retrieved information
will be

in binary format,
using
the format conversion functions
of
the
T
oolkit.

D
evelopers

can convert data

from

binary format to string representation
.

Refer to

Utils class for a sa
mple conversion implementation
.


The b
elow examples provide the usage of both the functions in Java and C# respectively.

Java Example


import

emiratesid.ae.readersmgt.*;

import

emiratesid.ae.utils.*;


CardInfo cardInfo = reader.getCardInfo();

try

{

char
[] csn = cardInfo.getCardSerialNumber();

char
[] chipSN = cardInfo.getChipSerialNumber();

char
[] cplc0101 = cardInfo.getCPLC0101();

char
[] cplc9f7f = cardInfo.getCPLC9F7F();

char
[]

isn = cardInfo.getIssuerSerialNumber();

char
[] irn = cardInfo.getIssuerReferenceNumber();

char
[] mocSN = cardInfo.getMOCSerialNumber();

char
[] mocAppState = cardInfo.getMOCAppletState();

char
[] mocAlgVer = cardInfo.getMOCAlgorithmVersion();

long

maxFailed

= cardInfo.getMaxFailedMatch();

int

cardVersion = cardInfo.

getCardVersion
();


String csnHex = Utils.CharArrayToHex(csn);

}
catch

(MiddlewareException e) {

e.printStackTrace();

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
23

of
140





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

National

Vision … For Better Future

C# Example


using

EmiratesId.AE.ReadersMgt;

using

EmiratesId.AE.Utils;


CardInfo

cardIn
fo = reader.GetCardInfo();

try

{

byte
[] csn = cardInfo.GetCardSerialNumber();

byte
[] chipSN = cardInfo.GetChipSerialNumber();

byte
[] cplc0101 = cardInfo.GetCPLC0101();

byte
[] cplc9f7f = cardInfo.GetCPLC9F7F();

byte
[] isn = cardInfo.GetIssuerSerialNumber();

byte
[] irn = cardInfo.GetIssuerReferenceNumber();

byte
[] mocSN = cardInfo.GetMOCSerialNumber();

byte
[] mocAppState = cardInfo.GetMOCAppletState();

byte
[] mocAlgVer = cardInfo.GetMOCAlgorithmVersion();

byte
[] maxFailed = cardInfo.GetMaxFailedMatch();

int

c
ardVersion = cardInfo.

G
etCardVersion
();


String

csnHex = Utils. ByteArrayToHex(csn);

}
catch

(
MiddlewareException

e) {


// … Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
24

of
140





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

National

Vision … For Better Future

5.6

Reading Card Holder Public Data

Using
a connected
PCSCReader object,
application can
read
the Card holder public data

from the card
.
T
he retrieved information
will be

in binary format,
and hence it
should be
converted to
S
tring format before us
ing them
.

R
efer to

Utils


C
lass for

sample conversion
implementation.

S
ome of the data retrieved are

Code
which

corresponds to a description,
f
or example
C
ard
holder occupation is s
tored

on the card as
occupat
ion
code
. To map the code into actual
occupation, refer to the
occupations (lookups)
table
published by EIDA
.

It is the developer’s
responsibility to
map
the relevant
code to the corresponding description
.

Note:

Codes lookups should be acquired regularly f
rom EIDA

In order to

optimize

the performance of

reading public data

from the card,
below flags
(parameters) are available
to
read
specific
set of data instead of reading all the public data

which is huge
:



Refresh flag:

set to true to read

the data from
th
e card

and also to enforce the
refreshing of the

cac
hed data
, set
it
to false
to read the already
ca
c
hed data (from
memory)
.



Photography flag

: set to true to read the photography, false otherwise



Non
-
modifiable data flag:

set to true to read the non
-
modif
iable data area on the ID
card
, false otherwise.



Modifiable data flag:

set to true to read the modifiable data on the ID card
, false
otherwise.



Validate signature flag:

set
it to true
to validate the signature
s

in public data file
s

on
the ID card
, false
o
t
herwise
.

The

toolkit verifies the signature using the d
ata signing certificates
located in the
folder
location configured in sm.cfg file.

Please refer to Appendix A

for more details
on how to configure the signing certificates folder location.

EIDA has i
ssued multiple
signing certificate
s therefore all of them must exist in the configured folder location
otherwise
if the signing certificate corresponding to the card couldn’t be found while
“SignatureValidation” flag set to true, an error returned if the c
ertificate is not found.

Please Note that the toolkit setup is copying all the signing certificates tell the date of
releasing version 2.5 of the toolkit, EIDA will deploy new certificates in future by
distributing a dedicated toolkit service packs
.

A

suc
cessful call
to

this function populates an instance of the class
CardHolderPublicData
with the read public data fields

and then these fields can be retrieved by calling member
function dedicated for each data filed in this
C
lass
,

T
he list of data fields in

this class
are
listed in

a
table in section
6.5.3




Below examples provide the usage of both the functions in Java and C# respectively.

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
25

of
140





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

National

Vision … For Better Future

Java Example


C# Example


using

EmiratesId.AE.PublicData;


try

{

PublicDataFacade

publicDataFacade = reader.GetPublicDataFacade();

CardHolderPublicData

publicData = publicDataFacade.ReadPublicData(
tru
e
,

true
,

true
,

true
,

true
);


byte
[] fullNameBin = publicData.GetFullName();

String

fullName = Utils.CharArrayToUTF8String(fullNameBin);

byte
[] sexBin = publicData.GetSex();

String

sex = Utils.CharArrayToUTF8String(sexBin);

byte
[] issueDateBin = publicData.
GetIssueDate();

String

issueDate = Utils.CharArrayToStringDate(issueDateBin);

byte
[] photography = publicData.GetPhotography();


// use publicData.getXXX as needed

//…


}
catch

(
MiddlewareException

e) {


// … Handle exceptions here

}

import

emiratesid.ae.publicdata.*;


// ... some code here ...


try

{

PublicDataFacade publicDataFacade =

reader.getPublicDataFacade();

Ca
rdHolderPublicData publicData =
publicDataFacade.readPublicData(
true
,
true
,
true
,
true
,
true
);


char
[] fullNameBin = publicData.getFullName();

String fullName = Utils.CharArrayToUTF8String(fullNameBin);

char
[] sexBin = publ
icData.getSex();

String sex = Utils.CharArrayToUTF8String(sexBin);

char
[] issueDateBin = publicData.getIssueDate();

String issueDate = Utils.CharArrayToStringDate(issueDateBin);

char
[] photography = publicData.getPhotography();


// use publicData.getXXX as

needed

//
...


}
catch

(MiddlewareException e) {

//
...

Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
26

of
140





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

National

Vision … For Better Future

5.7

Reading Card Holder Public Data Ex
tended

Read Card Holder Public Data

feature
i
s extended to support

reading additional
public
data
fields added in

V2

cards

such
as address
,
passport

information, Company name,
Qualification
,
Field of Study
, etc
..
.This func
tion expects the same parameters of the function

readPublicData


and additionally the belo
w parameter
s
:

ReadV2
Fields
: set it to true to read
V2 data specified above
(if the flag is set to true
while the
card inserted is
V1 cards
, the function throws an e
rror
)

ReadSignatureImage
: only if the above parameter is true, this parameter determines to
read the signature image or not.

Read
Address
: only if the
ReadV2Fields

parameter is true, this parameter determines to
read the Home and Work address fields or not
.

A successful call
to

this function populates an instance of the class
CardHolderPublicData
Ex

with the read public data fields

and then these fields can be retrieved by calling member
function dedicated for each data filed in this class
.

T
he list of data
fields in this class can be
identified from the table in section
6.5.4
.




Below examples provide the usage of both the functions in Java and C# respectively.

Java Example


import

emiratesid.ae.
publicdata.*;


try

{

PublicDataFacade publicDataFacade = reader.getPublicDataFacade();

CardHolderPublicDataEx publicDataEx =
publicDataFacade.readPublicDataEx(
true
,
true
,
true
,
true
,
true,true
,
true, true
);


char
[] fullNameBin = publicDataEx.getFullName();

String fullName = Utils.CharArrayToUTF8String(fullNameBin);

char
[] sexBin = publicDataEx.getSex();

String sex = Utils.CharArrayToUTF8String(sexBin);

char
[] issueDateBin = publicData.getIssueDate();

String issueDate = Utils.CharArrayToStringDate(issueDateB
in);

char
[] photography = publicDataEx.getPhotography();


char
[]
FieldofStudyEnglishBin=publicDataEx.getFieldofStudyEnglish();

String FieldofStudyEnglish= Utils.CharArrayToUTF8String
(FieldofStudyEnglishBin);


char
[]
FieldofStudyArabicBin=publicDataEx.getF
ieldofStudyArabic();

String FieldofStudyArabic= Utils.CharArrayToUTF8String
(FieldofStudArabicBin);



// use publicData
Ex
.getXXX as needed

//
...


}
catch

(MiddlewareException e) {

//
...

Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
27

of
140





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

National

Vision … For Better Future

C# Example


5.8

Read Public Data Contactless (MRZ Fields are entered manually)

Reading the public data from EIDA card is protected by Basic Access Control (BAC)
.

ReadPublicDataContactless

generates MRZ input required for deriving the BAC keys
.

MRZ
inpu
t is based on the CardNumber, DateOfBirth, and ExpiryDate that are accepted as
parameters to this function.

Once BAC keys are diversified,
T
oolkit establishes secure messaging with the card to read
the data files
and
then populate
s

the
CardHolderPublicDat
a
Ex

Class
with
the card holder
public data.

The t
ext fields in this class are encoded in UTF8

format
. If required, the conversion should
be carried

out

to convert it t
o a proper encoding before use, d
ate fields are represented in 4
bytes and it should be
decoded

properly
. Refer to the example on how to decode

it
.

In order to optimi
s
e reading public data performance as reading data from the smart card is
known to be slow, this function allows
reading

only specific sets of the data based on
combination o
f
the

same set of flags used for the ReadPublicDataEx function
.

A successful call of this function populates an instance of the class
CardHolderPublicData
Ex

with the read public data fields

and then these fields can be retrieved by calling member
using

EmiratesId.AE.PublicData;


try

{

Publ
icDataFacade

publicDataFacade = reader.GetPublicDataFacade();

CardHolderPublicDataEx

publicDataEx =
publicDataFacade.ReadPublicDataEx(
true
,

true
,

true
,

true
,

true,true,
true, true
);


byte
[] fullNameBin = publicDataEx.GetFullName();

String

fullName = Utils.
ByteArrayToUTF8String(fullNameBin);

byte
[] sexBin = publicDataEx.GetSex();

String

sex = Utils.

ByteArrayToUTF8String(sexBin);

byte
[] issueDateBin = publicDataEx.GetIssueDate();

String

issueDate = Utils.ByteArrayToStringDate(issueDateBin);

byte
[] photograph
y = publicDataEx.GetPhotography();

byte
[]
FieldofStudyEnglishBin=publicDataEx.getFieldofStudyEnglish();

String
FieldofStudyEnglish= Utils.
Byte
ArrayToUTF8String
(FieldofStudyEnglishBin);


byte
[]
FieldofStudyArabicBin=publicDataEx.getFieldofStudyArabic();

St
ring
FieldofStudyArabic= Utils.
Byte
ArrayToUTF8String
(FieldofStudArabicBin);



// use publicDataEx.getXXX as needed

//…


}
catch

(
MiddlewareException

e) {


// … Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
28

of
140





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

National

Vision … For Better Future

function

dedicated for each data filed in this class, the list of data fields in this class can be
identified from the table in section
6.5.4




Note:

1.

MW_ReadPublicDataContactless

works only with contactless PC
\
SC readers.

2.

MW_ReadPublicDataContactless

works only
with
V2 Cards


Below examples provide the usage of both the functions in Java and C# respectively.

Java Example


import

emiratesid.ae.publicdata.*;


// ... some code here...


try

{

P
ublicDataFacade

publicDataFacade = reader.getPublicDataFacade();


// user was prompted to enter MRZ fields Manually

char
[] cn =
// card number

char
[] birthDate =
// date of birth

char
[] expiryDate =
// card expiry date

CardHolderPublicDataEx

publicData =
p
ublicDataFacade.
read
PublicDataContactless
(
cn, birthDate, expiryDate,
true
,
true
,
true
,
true
,
true
,

true
,
true
,
true
);


char
[] fullNameBin = publicData.getFullName();

String fullName = Utils.CharArrayToUTF8String(fullNameBin);

char
[] sexBin = publicData.get
Sex();

String sex = Utils.CharArrayToUTF8String(sexBin);

char
[] issueDateBin = publicData.getIssueDate();

String issueDate = Utils.CharArrayToStringDate(issueDateBin);

char
[] photography = publicData.getPhotography();


// use publicData.getXXX as needed

//
...


}
catch

(MiddlewareException e) {

//
...

Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
29

of
140





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

National

Vision … For Better Future

C# Example


5.9

Read Public Data Contactless (with MRZ Reader)

Reading the public data from EIDA card is protected by Basic Access Control (BAC)
.

ReadPublicDataContactlessWithMRZData

expects the MRZ lines read by M
RZ reader as an
input that is used to diversify BAC keys
.

Note: new line and cartridge return characters must be removed from the MRZ text returned
from an MRZ reader before passing it to the function
ReadPublicDataContactlessWithMRZData


Once BAC keys are

diversified,
T
oolkit establishes secure messaging with the card to read
the data files .then populate the
CardHolderPublicDataEx

Class
with
the card holder public
data.

The t
ext fields in this class are encoded in UTF8. If required, the conversion should

be
carried need to convert it t
o a proper encoding before use, d
ate fields are represented in 4
bytes and it should be decoded. Refer to the example on how to decode

it
.

In order to optimi
s
e reading public data performance as reading data from the sma
rt card is
known to be slow, this function allows to read only specific sets of the data based on
combination of
the

same set of flags used for the ReadPublicDataEx function
.

A successful call
to

this function populates an instance of the class
CardHolderP
ublicData
Ex

with the read public data fields

and then these fields can be retrieved by calling member
function dedicated for each data filed in this class, the list of data fields in this class can be
identified from the table in section
6.5.4




using

EmiratesId.AE.PublicData;


try

{

PublicDataFacade

publicDataFacade = reader.GetPublicDataFacade();


//
user was prompted to enter MRZ fields Manually

byte
[] cn =
// card number

b
yte
[] birthDate =
// date of birth

byte
[] expiryDate =
// card expiry date

CardHolderPublicDataEx

publicData =
publicDataFacade.
R
ead
PublicDataContactless
(
cn, birthDate, expiryDate,
true
,
true
,
true
,
true
,
true
,

true
,
true
,
true
);

byte
[] fullNameBin = publi
cData.GetFullName();

String

fullName = Utils.CharArrayToUTF8String(fullNameBin);

byte
[] sexBin = publicData.GetSex();

String

sex = Utils.CharArrayToUTF8String(sexBin);

byte
[] issueDateBin = publicData.GetIssueDate();

String

issueDate = Utils.CharArrayToStr
ingDate(issueDateBin);

byte
[] photography = publicData.GetPhotography();


// use publicData.getXXX as needed

//…


}
catch

(
MiddlewareException

e) {


// … Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
30

of
140





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

National

Vision … For Better Future


Note:

1.

MW_ReadPublicDataContactlessWithMRZData

works only with contactless
PC
\
SC readers.

2.

MW_ReadPublicDataContactlessWithMRZData

works only V2 Cards


Below examples provide the usage of both the functions in Java and C# respective
ly.

Java Example


import

emiratesid.ae.publicdata.*;


// ... some code here...


try

{

PublicDa
taFacade

publicDataFacade = reader.getPublicDataFacade();


// reading with MRZ data

char
[] mrzData =
// read MRZ data here
...

CardHolderPublicDataEx

publicData =
publicDataFacade.

readPublicDataContactlessWithMRZData
(
mrzData,
true
,
true
,
true
,
true
,
true
,

true
,
true
,
true
);


char
[] fullNameBin = publicData.getFullName();

String fullName = Utils.CharArrayToUTF8String(fullNameBin);

char
[] sexBin = publicData.getSex();

String sex = Utils.CharArrayToUTF8String(sexBin);

char
[] issueDateBin = publicData.getIssueD
ate();

String issueDate = Utils.CharArrayToStringDate(issueDateBin);

char
[] photography = publicData.getPhotography();


// use publicData.getXXX as needed

//
...


}
catch

(MiddlewareException e) {

//
...

Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
31

of
140





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

National

Vision … For Better Future

C# Example



5.10

Reading Family Book Data

Using a connected PCSCReader object, application can read the Card holder family book
data from the card. The retrieved information will be in
binary format, and hence it should be
converted to String format before using them.

Refer to ‘Utils’ Class for sample conversion
implementation.

In order to read
family book data
,
T
oolkit must be authenticated with the ID applet via
dedicated cryptography
sequence that requires access to EIDA secure messaging module

from the card requires secure messaging

Read family book data
function can be executed locally if EIDA secure messaging module
(SAM smart card or HSM) attached to the PC locally
.

T
his function
can

also

be executed

with Soft
ware

SAM in case test cards used
.

P
lease refer to
Appendix A

for more details on
configuring EIDA secure messaging.

Family book container exists only on V2 cards hence
executing this function
with V1 cards
will return an erro
r
.


In order to optimize the performance of reading family book data a refresh flag is used to

read the already cached data (from memory).



Refresh flag:

set to true to read the data from the card and
,
set to false to

will read
cached data


using

EmiratesId.AE.PublicD
ata;


try

{

PublicDataFacade

publicDataFacade = reader.GetPublicDataFacade();


// reading with MRZ data

byte
[] mrzData =
// read MRZ data here...

CardHolderPublicDataEx

publicData =
publicDataFacade.

R
eadPublicDataContactlessWithMRZData
(
mrzData,
true
,
true
,
true
,
true
,
true
,

true
,
true
,
true
);

byte
[] fullNameBin = publicData.GetFullName();

String

fullName = Utils.CharArrayToUTF8String(fullNameBin);

byte
[] sexBin = publicData.GetSex();

String

sex = Utils.CharArrayToUTF8String(sexBin);

byte
[] issueDateBin = p
ublicData.GetIssueDate();

String

issueDate = Utils.CharArrayToStringDate(issueDateBin);

byte
[] photography = publicData.GetPhotography();


// use publicData.getXXX as needed

//…


}
catch

(
MiddlewareException

e) {


// … Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
32

of
140





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

National

Vision … For Better Future

Java Example


C# Example


import

emir
atesid.ae.publicdata.*;


try

{

// make sure that UAEIDCardLibJavaWrapper.LoadConfiguration() is called

// before executing the following code, and sm.cfg is configured


FamilyBookDataFacade familyBook
DataFacade =
reader.get
FamilyBookDataFacade
();

FamilyBoo
kData familyBookData =
familyBookDataFacade
.
readFamilyBookData(true)
;


char
[] firstNameBin

=
familyBookData.getChild1
()
.getChildFirstNameArabic()
;

String firstName

=
Utils.CharArrayToUTF8String(first
NameBin);

char
[] sexBin = familyBookData
.
getChild1().
getS
ex();

String sex = Utils.CharArrayToUTF8String(sexBin);

char
[]
Date
OfBirth
Bin = publicData.getIssueDate();

String DateOfBirth

= Utils.CharArrayToStringDate(issueDateBin);


// use familyBookData
.getXXX as needed

//
...


}
catch

(MiddlewareException e) {

//
.
..

Handle exceptions here

}

using

EmiratesId.AE.PublicData;


try

{

// make sure that IDCardWrapper.LoadConfiguration() is called

// before executing the following code, and sm.cfg is configured


FamilyBookDataFacade

FamilyBookDataFacade =
reader.GetFamily
BookDataFacade();

FamilyBookData

FamilyBookData =
familyBookDataFacade.ReadFamilyBookData(
true
);


//…

byte
[]
firstNameBin

=
familyBookData.getChild1
()
.getChildFirstNameArabic()
;

String

firstName

=
Utils.ByteArrayToUTF8String(first
NameBin);

byte
[]
sexBin =
familyBookData
.
getChild1().
getSex();

String

sex = Utils.
Byte
ArrayToUTF8String(sexBin);

byte
[]
Date
OfBirth
Bin = publicData.getIssueDate();

String

DateOfBirth

= Utils.
Byte
ArrayToStringDate(issueDateBin);


// use familyBookData
.getXXX as needed

//
...



}
catc
h

(
MiddlewareException

e) {


// … Handle exceptions here

}

INTERNAL


Fortunabrontide_8a4f4c6e
-
Acd2
-
42e9
-
9e64
-
927f0c95e41c.Doc






Page
33

of
140





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

National

Vision … For Better Future

5.11

C
hecking Card Genuine


This
function is used to verify
that
the presented

ID card is authentic. Verifying an ID card is
authentic and the card is issued by EIDA involves
cryptographic chal
lenge response
sequence where the
T
oolkit sends a random challenge to the card and hence the card
applies
internal
cryptographic operations
and provides
with response corresponds to the
challenge
.

T
he
T
oolkit then verifies the card response
and makes sure
that
the keys and
cryptographic algorithm used by the card is genuine,

and
therefore the card

is authentic
issue
d

by EIDA.

In order to carry out this function
EIDA secure messaging

(SM)

module
.

5.11.1

Verify
ing

Card Genuine

in
local mode

Check card genuine
functi
on
can be executed locally if
EIDA
secure messaging module
(
SAM

smart card
or HSM)
attached to the PC
locally
,

Alternatively Check Card genuine
function can be executed remotely
using
EIDA
’s

remote
Secure Messaging
web
service

as
explained in the
following

section
.



This section provides the sample code
on how to
utilize the

local S
A
M

/
HSM

in order to
check the card is genuine
. Next section
describes the remote execution of this function
.