DOT Android NFC library

v6.3.1

Introduction

DOT Android NFC provides a component for NFC reading which is easy to integrate into an Android application. Supported documents are those which implement ICAO Doc 9303: Machine Readable Travel Documents as specified by International Civil Aviation Organization (ICAO).

Requirements

DOT Android NFC has the following requirements:

Minimum Android API level 21
Minimum Kotlin Gradle plugin version 1.6.0 (if used)

Distribution

Maven Repository

DOT Android NFC is distributed as an Android library (.aar package) stored in the Innovatrics maven repository.

In order to integrate DOT Android NFC into your project, the first step is to include the Innovatrics maven repository and Google repository to your top level build.gradle file.

build.gradle

allprojects {
    repositories {
        maven {
            url 'https://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependency on DOT Android NFC library in the module’s build.gradle file. Dependencies of this library will be downloaded alongside the library.

build.gradle

dependencies {
    //…
    implementation "com.innovatrics.dot:dot-nfc:$dotVersion"
    //…
}

Permissions

DOT Android NFC declares the following permission in AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.NFC" />

Basic Setup

Logging

Although logging is disabled by default, it can be enabled explicitly by using the following method from the com.innovatrics.dot.core.Logger class.

Logger.setLoggingEnabled(true);

The appropriate place for this call is within the onCreate() method of your subclass of android.app.Application. Each TAG of a log message starts with the prefix dot-nfc:.

This setting enables logging for all DOT Android libraries.

Keep in mind that logging should be used just for debug purposes as it might produce a lot of log messages.

Components

Overview

DOT Android NFC provides a non-UI component for NFC reading. You may build your own UI using the DOT Android NFC functionality.

List of Non-UI Components

NFC TRAVEL DOCUMENT READER: The component for reading NFC enabled travel documents.
FLAT TAG STRUCTURE PARSER: The component for parsing flat tag structure in a data group as defined in Doc 9303.

Non-UI Components

NFC Travel Document Reader

The NfcTravelDocumentReader interface provides NFC reading functionality.

Create a NfcTravelDocumentReader:

Set<X509Certificate> authorityCertificates = CertificatesFactory.create(inputStream);
NfcTravelDocumentReaderConfiguration configuration = new NfcTravelDocumentReaderConfiguration.Builder()
    .timeoutMillis(timeoutMillis)
    .authorityCertificates(authorityCertificates)
    .build();
NfcTravelDocumentReader nfcTravelDocumentReader = NfcTravelDocumentReaderFactory.create(configuration);

To read NFC data, call the following method on the background thread:

TravelDocument travelDocument = nfcTravelDocumentReader.read(tag, nfcKey);

Tag represents NFC Tag discovered by NfcAdapter. NfcKey is the access key to NFC data.

In case, when server-side authentication of the chip is required, use the read() method with activeAuthenticationChallenge argument. If the Active Authentication protocol is supported by the chip, it will be used for the authentication of the chip and the response (signature) will be returned in TravelDocument data class.

TravelDocument travelDocument = nfcTravelDocumentReader.read(tag, nfcKey, activeAuthenticationChallenge);

Flat Tag Structure Parser

The FlatTagStructureParser interface parses a byte array into a flat map of data elements.

Create a FlatTagStructureParser:

FlatTagStructureParser flatTagStructureParser = FlatTagStructureParserFactory.create();

To parse a Data Group value, call the following method:

Map<Short, byte[]> elements = flatTagStructureParser.parse(bytes);

Following data structure is expected as an input:

ELEMENT_1_TAG, ELEMENT_1_LENGTH, ELEMENT_1_VALUE, ..., ELEMENT_N_TAG, ELEMENT_N_LENGTH, ELEMENT_N_VALUE

Such a value is parsed into this map:

Table 1. Map of Data Elements
Tag	Value
`ELEMENT_1_TAG`	`ELEMENT_1_VALUE`
…	…
`ELEMENT_N_TAG`	`ELEMENT_N_VALUE`

For example, let the Data Group value be:

\u005C\u0002\u005F\u005B\u005F\u005B\u0008SPECIMEN

Then the resulting map is as follows:

Table 2. Example of a map of Data Elements
Tag	Length	Value
`0x5C`	`0x02`	`0x5F_5B`
`0x5F_5B`	`0x08`	`SPECIMEN` (shown as text for readability)

Some country authorities may use this structure in the Optional Details. This data is present in TravelDocument.optionalDetails as a result of the NFC reading.

Technical release. No changes.

6.3.0 - 2023-08-17

Technical release. No changes.

6.2.1 - 2023-07-27

Fixed

PACE access protocol authentication on some chips.

6.2.0 - 2023-07-26

Technical release. No changes.

6.1.0 - 2023-07-07

Fixed

Explicit challenge-response when Active Authentication protocol results as denied.

6.0.0 - 2023-06-14

Technical release. No changes.

5.5.1 - 2023-06-06

Technical release. No changes.

5.5.0 - 2023-04-26

Added

Explicit challenge-response for Active Authentication in API suitable for server-side validation.
Method NfcTravelDocumentReader.read() with activeAuthenticationChallenge argument.
Property ChipAuthenticationStatus.activeAuthenticationResponse.

5.4.2 - 2023-04-04

Fixed

Stability issue.

5.4.1 - 2023-03-28

Technical release. No changes.

5.4.0 - 2023-03-24

Technical release. No changes.

5.3.0 - 2023-03-20

Technical release. No changes.

5.2.0 - 2023-03-07

Added

TravelDocument: Property authenticationStatus.
Class AuthenticationStatus.
Class ChipAuthenticationStatus.
Class DataAuthenticationStatus.

Removed

TravelDocument: Property activeAuthenticationStatus.
TravelDocument: Property passiveAuthenticationStatus.

5.1.0 - 2023-02-06

Changed

Minimum Kotlin Gradle plugin version to 1.6.0.

5.0.0 - 2023-01-30

Changed

Target Android API level to 33.
New SDK versioning: All libraries (DOT Document, DOT Face, DOT Face Lite and DOT NFC) are released simultaneously with a single version name. Libraries with the same version name work correctly at build time and at run time.
Minimum Kotlin Gradle plugin version to 1.7.0.

2.3.4 - 2022-09-26

Fixed

Issues if the consumer application is obfuscated (consumer proguard rules).

2.3.3 - 2022-09-16

Fixed

Reading NFC if the Data Group 13 is present.

2.3.2 - 2022-08-18

Fixed

Compatibility with latest DOT libraries.

2.3.1 - 2022-07-26

Fixed

Integration manual: TravelDocument class.

2.3.0 - 2022-07-21

Added

Method DotNfcLibrary.getVersionName().
Class attribute TravelDocument.ldsMasterFile.
Class LdsMasterFile.
Class Lds1eMrtdApplication.
Class Lds1ElementaryFile.

Fixed

Parsing TravelDocument.machineReadableZoneInformation.optionalData for TD3 documents.
Class attribute TravelDocument.encodedIdentificationFeaturesFace is non-null.