DOT Android NFC library

v7.4.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"
    //…
}

Licensing

In order to use DOT SDK in other apps, it must be licensed. The license can be compiled into the application as it is bound to the application ID specified in build.gradle:

build.gradle
defaultConfig {
    applicationId "com.innovatrics.dot.sample"
    //…
}

The application ID can be also retrieved in runtime by calling DotSdk.getApplicationId().

In order to obtain the license, please contact your Innovatrics’ representative specifying the application ID. If the application uses build flavors with different application IDs, each flavor must contain a separate license. Put the license file into the raw resource folder.

Permissions

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

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

Transaction Reporting

DOT Android NFC reports transactions to a remote service. Read more details in the Product Documentation.

Basic Setup

Initialization

Before using any of the components, you need to initialize DOT SDK with the license and DotNfcLibrary object.

InitializeDotSdkUseCase class in the Samples project shows how to initialize DOT SDK with DotNfcLibrary. DotSdk.initialize() method should be called on background thread.

Keep in mind that if you try to use any component without initialization, it will throw an exception.

Deinitialization

When a process (e.g. onboarding) using the DOT Android NFC has been completed, it is usually a good practice to free the resources used by it.

You can perform this by calling DotSdk.deinitialize(). If you want to use the DOT Android NFC components again after that point, you need to call DotSdk.initialize() again. This shouldn’t be performed within the lifecycle of individual Android components.

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.

List of UI Components

UI NFC TRAVEL DOCUMENT READER

A visual component for reading NFC enabled travel documents.

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.

UI Components

UI NFC Travel Document Reader

A ready-to-use component for incorporating NFC reading capabilities into your application. It includes a set of UI elements to guide the user through the NFC reading process.

This component is based on a Fragment from AndroidX. In order to use it, an abstract NfcTravelDocumentReaderFragment must be subclassed.

The NfcTravelDocumentReaderFragment requires a configuration. Configuration parameters are wrapped by the NfcTravelDocumentReaderFragment.Configuration data class and you must put them as a Serializable under the NfcTravelDocumentReaderFragment.CONFIGURATION key to the fragment arguments.

Override the onSucceeded method to handle successful NFC document reading. Similarly, override the onFailed method to manage reading failures. The reading process of the NFC Travel Document is tied to the fragment’s lifecycle. To cancel the reading process, simply transition the fragment to the destroyed state, for example, by navigating to another fragment.

UI of the fragment can be customized.

Strings

You can override the string resources and provide alternative strings for supported languages using the standard Android localization mechanism.

<string name="dot_nfc_nfc_travel_document_reader_searching_title">Searching for NFC chip…</string>
<string name="dot_nfc_nfc_travel_document_reader_searching_subhead">Slide your phone gently on the surface of the document until we find the right position.</string>
<string name="dot_nfc_nfc_travel_document_reader_reading_title">Hold still</string>
<string name="dot_nfc_nfc_travel_document_reader_reading_subhead">Please keep both device and document still.</string>
Styles

Text views can be styled by overriding the parent style in the application. To customize the appearance of text views, you can override the following styles:

<style name="Dot.Title" parent="TextAppearance.AppCompat.Title" />
<style name="Dot.Subhead" parent="TextAppearance.AppCompat.Subhead" />
Drawables

You can also override the following drawable resources.

R.drawable.dot_nfc_nfc_travel_document_reader_reading
R.drawable.dot_nfc_nfc_travel_document_reader_searching

The type of R.drawable.dot_nfc_nfc_travel_document_reader_searching must be AnimatedVectorDrawable.

Appendix

Changelog

7.4.1 - 2024-03-27

Changed
  • Target Android API level to 34.

7.4.0 - 2024-03-18

Added
  • Interface NfcTravelDocumentReader.AccessEstablishmentStartedListener.

  • Interface NfcTravelDocumentReader.ElementaryFilesReadingProgressUpdatedListener.

  • Interface NfcTravelDocumentReader.DataAuthenticationStartedListener.

  • Interface NfcTravelDocumentReader.SucceededListener.

  • Interface NfcTravelDocumentReader.FailedListener.

  • Class NfcTravelDocumentReader.Listeners.

  • Method NfcTravelDocumentReader.read(tag: Tag, nfcKey: NfcKey, listeners: Listeners).

  • Method NfcTravelDocumentReader.read(tag: Tag, nfcKey: NfcKey, activeAuthenticationChallenge: ByteArray?, listeners: Listeners).

  • Enum Lds1ElementaryFile.Id.

  • Property Lds1ElementaryFile.id.

  • Class NfcTravelDocumentReaderFragment.

  • Class NfcTravelDocumentReaderFragment.Configuration.

  • String resource dot_nfc_nfc_travel_document_reader_searching_title.

  • String resource dot_nfc_nfc_travel_document_reader_searching_subhead.

  • String resource dot_nfc_nfc_travel_document_reader_reading_title.

  • String resource dot_nfc_nfc_travel_document_reader_reading_subhead.

  • Style resource Dot.Title.

  • Style resource Dot.Subhead.

  • Drawable resource dot_nfc_nfc_travel_document_reader_reading

  • Drawable resource dot_nfc_nfc_travel_document_reader_searching

Changed
  • Class NfcKey implements Serializable.

Fixed
  • Issue with chip authentication with some cards.

  • Issue with data authentication with some cards.

  • Exceptions throwing.

7.3.0 - 2024-02-23

Added
Fixed
  • Issue with chip authentication with some cards.

  • Issue with data authentication with some cards.

7.2.2 - 2024-02-07

Fixed
  • Issue with reading cards that do not support short file identifiers.

7.2.1 - 2024-02-05

Added
  • Property REQUIRE_SECURE_ENV with value 1 under the <application> in Android manifest.

7.2.0 - 2023-12-28

  • Technical release. No changes.

7.1.0 - 2023-12-14

Changed
  • Method NfcTravelDocumentReader.read() throws NfcTravelDocumentReaderException instead of RuntimeException.

  • Access Control mechanism reworked. BAC protocol is used by default. PACE protocol is used only if BAC protocol fails or BAC is not available.

7.0.2 - 2023-12-05

  • Technical release. No changes.

7.0.1 - 2023-11-21

Fixed
  • Performance issue.

7.0.0 - 2023-11-02

Added
  • Class DotSdk.

  • Class DotSdkConfiguration.

  • Interface DotLibrary.

  • License file is required. To obtain one, please contact support@innovatrics.com.

Changed
  • Class DotNfcLibrary reworked.

6.5.2 - 2023-10-20

  • Technical release. No changes.

6.5.1 - 2023-10-19

  • Technical release. No changes.

6.5.0 - 2023-10-04

  • Technical release. No changes.

6.3.1 - 2023-08-21

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

2.2.2 - 2022-05-27

Fixed
  • Stability issues.

2.2.1 - 2022-01-25

Added
  • Class CertificatesFactory.

Fixed
  • Authority certificates compatibility on Android API level ⇐ 27.

  • Handling of lost connection.

2.2.0 - 2022-01-21

Added
  • Flat Tag Structure Parser component.

  • Interface FlatTagStructureParser.

  • Class FlatTagStructureParserFactory.

2.1.0 - 2022-01-19

Added
  • Class OptionalDetails.

  • Class attribute TravelDocument.optionalDetails.

Changed
  • Data type of AdditionalPersonalDetails.nameOfHolder to NameOfHolder.

Fixed
  • Passive Authentication for documents that are out of their validity period.

  • Resolving JPEG image format (enum ImageFormat).

  • Passive Authentication.

2.0.0 - 2021-12-02

Added
  • Enum AccessControlProtocol.

  • Class AdditionalDocumentDetails.

  • Class AdditionalPersonalDetails.

  • Class DisplayedSignatureOrUsualMark.

  • Class EncodedIdentificationFeaturesFace.

  • Class MachineReadableZoneInformation.

  • Class NameOfHolder.

  • Class NfcTravelDocumentReaderConfiguration.

  • Class NfcTravelDocumentReaderFactory.

Changed
  • groupId com.innovatrics.android to com.innovatrics.dot.

  • Minimum Android API level to 21.

  • Target Android API level to 31.

  • Class TravelDocumentAccessFailedException to AccessControlException.

  • Enum ActiveAuthentication.Status to ActiveAuthenticationStatus.

  • Enum PassiveAuthentication.Status to PassiveAuthenticationStatus.

  • Class NfcTravelDocumentReader to an interface NfcTravelDocumentReader.

  • Structure of class TravelDocument.

Fixed
  • Active Authentication.

1.0.0 - 2020-05-27

Added
  • First major release.