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.

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.