DOT Android NFC library
v5.3.0
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.
allprojects {
repositories {
google()
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.
dependencies {
//…
implementation "com.innovatrics.dot:dot-nfc:$dotVersion"
//…
}
Permissions
DOT Android NFC declares the following permission in 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);
NfcTravelDocumentReaderConfiguration.Builder
arguments
(Optional)
[10000]
int timeoutMillis
- The timeout only applies to ISO-DEP I/O operations on a Tag.(Optional)
[-]
Set<X509Certificate> authorityCertificates
- Certificates of trusted authorities. Certificates are required to successfully execute Passive Authentication.
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.
NfcKey
class
NfcKey
is created from the travel document number, date of birth and date of expiry.
NfcKey nfcKey = NfcKey.of(documentNumber, dateOfExpiry, dateOfBirth);
TravelDocument
class
This data class represents the travel document. The following attributes are available:
LdsMasterFile ldsMasterFile
- Binary content of the Logical Data Structure Master File according ICAO Doc 9303, Machine Readable Travel Documents, Part 10: Logical Data Structure (LDS) for Storage of Biometrics and Other Data in the Contactless Integrated Circuit (IC) (See: Section 2: Structure of Doc 9303-10).String ldsVersion
- Logical Data Structure version.AccessControlProtocol accessControlProtocolUsed
- BAC or PACE access control protocol.AuthenticationStatus authenticationStatus
- Authentication status of the data (Passive Authentication protocol) and the chip (either PACE-CAM protocol, Chip Authentication protocol or Active Authentication protocol, if at least one of them is supported by the chip).MachineReadableZoneInformation machineReadableZoneInformation
- Parsed Data Group 1.EncodedIdentificationFeaturesFace encodedIdentificationFeaturesFace
- Parsed Data Group 2.DisplayedSignatureOrUsualMark displayedSignatureOrUsualMark
- Parsed Data Group 7.AdditionalPersonalDetails additionalPersonalDetails
- Parsed Data Group 11.AdditionalDocumentDetails additionalDocumentDetails
- Parsed Data Group 12.OptionalDetails optionalDetails
- Binary content Data Group 13. See Flat Tag Structure Parser in order to parse the content.
Reading Process
Travel document reading process consists of four steps:
Access establishment
Authentication of data and chip
Reading data
Parsing data into structures
For more details read the ICAO Doc 9303: Machine Readable Travel Documents specification.
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:
Tag | Value |
|
|
… | … |
|
|
For example, let the Data Group value be:
\u005C\u0002\u005F\u005B\u005F\u005B\u0008SPECIMEN
Then the resulting map is as follows:
Tag | Length | Value |
|
|
|
|
|
|
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.
Appendix
Changelog
5.3.0 - 2023-03-20
Technical release. No changes.
5.2.0 - 2023-03-07
Added
TravelDocument
: PropertyauthenticationStatus
.Class
AuthenticationStatus
.Class
ChipAuthenticationStatus
.Class
DataAuthenticationStatus
.
Removed
TravelDocument
: PropertyactiveAuthenticationStatus
.TravelDocument
: PropertypassiveAuthenticationStatus
.
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
toNameOfHolder
.
Fixed
Passive Authentication for documents that are out of their validity period.
Resolving
JPEG
image format (enumImageFormat
).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
tocom.innovatrics.dot
.Minimum Android API level to 21.
Target Android API level to 31.
Class
TravelDocumentAccessFailedException
toAccessControlException
.Enum
ActiveAuthentication.Status
toActiveAuthenticationStatus
.Enum
PassiveAuthentication.Status
toPassiveAuthenticationStatus
.Class
NfcTravelDocumentReader
to an interfaceNfcTravelDocumentReader
.Structure of class
TravelDocument
.
Fixed
Active Authentication.
1.0.0 - 2020-05-27
Added
First major release.