Usage Guide

Quick Start

1. Acquire an IsoDep

Acquire an IsoDep from Android. Refer to the NFC basics guide on how to configure your app and allow your Activity to receive the ACTION_TECH_DISCOVERED intent.

2. Read and Verify

Initialize EmrtdReader, load a CSCA master list, and call readAndVerify:

val isoDep: IsoDep // IsoDep acquired from Android

// master list containing Country Certificates from a trusted source.
val masterListFileInputStream: InputStream = assets.open("masterlist.ml") 

// Initialize EmrtdReader
val emrtdReader = EmrtdReader() 
emrtdReader.readMasterList(masterListFileInputStream) 

// Access Key values from the MRZ
val documentNumber = "123456789"
val dateOfBirth = "970101" // yyMMdd
val dateOfExpiry = "221212" // yyMMdd

try {
    // Access chip using the MRZ Info and get results
    val emrtdResult = emrtdReader.readAndVerify( 
        isoDep, documentNumber, dateOfBirth, dateOfExpiry 
    ) 

    // MRZ Info from mandatory DataGroup 1
    val mrzInfo: MRZInfo = emrtdResult.dg1File.mrzInfo
    // Photo of the face from mandatory DataGroup 2
    val facePhotoBitmap: Bitmap = emrtdResult.facePhotoBitmap

    // Integrity and Authenticity of the read DataGroups
    val passiveAuthentication: Boolean = emrtdResult.passiveAuthenticationResult.evaluate()
    // Active Authentication Result { SUCCESS, FAILED, UNAVAILABLE }
    val activeAuthentication: CheckResult = emrtdResult.activeAuthenticationResult
    // Chip Authentication Result { SUCCESS, FAILED, UNAVAILABLE }
    val chipAuthentication: CheckResult = emrtdResult.chipAuthenticationResult
} catch (e: TagLostException) {
    // Connection to NFC Tag lost. Hold the phone and the document steady and try again.
} catch (e: AccessControlProtocolException) {
    // Verify the Access Key data (CAN or MRZ Info)
} catch (e: EmrtdReaderException) {
    // eMRTD Reader exception. Try again.
}

INFO

CSCA master list You must provide a CSCA master list to verify the eMRTD (ICAO Doc 9303 Part 12). The German Federal Office for Information Security (BSI) publishes an extensive and regularly updated CSCA master list.

Reading Selected Data Groups

By default, a read returns DG1 (MRZ), DG2 (face image), and the optional data groups the document carries. If you only need some of them, pass a DataGroupSet. Reading less is faster, because DG2 alone accounts for most of the chip reading time:

// MRZ and face image only
val emrtdResult = emrtdReader.readAndVerify(
    isoDep, documentNumber, dateOfBirth, dateOfExpiry,
    DataGroupSet.MINIMAL_KYC 
)

read takes the same parameter, and both accept it with a CAN as well. Besides the predefined selections you can combine data groups freely, e.g. DataGroupSet.of(1, 11) or DataGroupSet.STANDARD.union(DataGroupSet.of(13)).

Selection	Data Groups	Use Case
DataGroupSet.MINIMAL	DG1	MRZ data alone, no biometrics
DataGroupSet.MINIMAL_KYC	DG1, DG2	MRZ plus face image
DataGroupSet.STANDARD	DG1, DG2, DG7, DG11, DG12	Same as a read without a selection
DataGroupSet.ALL	DG1 to DG16	All sixteen data groups

How a selection behaves:

• The SOD is always read, and Passive Authentication covers the data groups that were actually read. A reduced selection shows up as fewer entries in the result.
• Selected data groups the document does not contain are skipped, and an optional data group that fails to read is left out instead of ending the session. DG3 and DG4 are the common case: they need Extended Access Control, which this SDK does not implement, so DataGroupSet.ALL reads what it can and skips those two.
• DG1 and DG2 must read successfully while they are part of the selection, otherwise the read fails.
• The selection never affects the authenticity checks: DG14 (Chip Authentication) and DG15 (Active Authentication) are read whenever the document carries them.

See Relevant Data Groups for what each data group contains.

Using With CAN

For documents that support PACE with a Card Access Number (a 6-digit number printed on the document):

val emrtdResult = emrtdReader.readAndVerify(isoDep, "123456") // 6-digit CAN

INFO

CAN authentication only works with documents that support PACE (Password Authenticated Connection Establishment). It cannot be used with BAC (Basic Access Control).

Error Handling

The SDK throws specific exceptions depending on the type of error:

Exception	Description
TagLostException	NFC connection lost (passport moved away). Hold the device steady and try again.
AccessControlProtocolException	Access control failed. Verify the access key values (CAN or MRZ info).
EmrtdReaderException	General eMRTD reader error.