NkkinSoft.Jmrtd.Binding 0.8.3

JMRTD .NET 10 Android Binding Library

.NET 10 Android binding library for JMRTD (Java Machine Readable Travel Documents) version 0.8.3.

JMRTD is a Java library for reading and processing electronic Machine Readable Travel Documents (eMRTD) such as ePassports. This binding allows you to use JMRTD in your .NET 10 Android and .NET MAUI applications.

📋 Features

• ✅ Full binding of JMRTD 0.8.3
• ✅ Support for reading ePassports and other eMRTD documents
• ✅ BAC (Basic Access Control) support
• ✅ PACE (Password Authenticated Connection Establishment) support
• ✅ Active Authentication (AA)
• ✅ Extended Access Control (EAC)
• ✅ Biometric data extraction (face, fingerprint, iris)
• ✅ .NET 10 compatible with modern Android development
• ✅ Trim-safe for AOT compilation

🔧 Requirements

• .NET 10 SDK or later
• Android API 21+ (Android 5.0 Lollipop or higher)
• Visual Studio 2025 (v17.13+) or VS Code with C# Dev Kit
• Android device with NFC (for reading physical documents)

📦 Installation

Via NuGet (once published)

dotnet add package Jmrtd.Binding --version 0.8.3

Via Local Build

1. Clone this repository
2. Build the project:

   dotnet build JrmtdBinding.csproj -c Release
   

3. Reference the generated .nupkg or .dll in your project

🚀 Quick Start

Basic Usage in .NET MAUI or .NET Android

using Org.Jmrtd;
using Org.Jmrtd.Lds;
using Android.Nfc;
using Android.Nfc.Tech;

public class PassportReader
{
    public async Task<PassportData> ReadPassportAsync(Tag tag, string documentNumber, 
        string dateOfBirth, string dateOfExpiry)
    {
        try
        {
            // Get IsoDep from NFC tag
            var isoDep = IsoDep.Get(tag);
            if (isoDep == null)
                throw new Exception("Not an ISO-DEP tag");

            await isoDep.ConnectAsync();

            // Create card service
            var cardService = new PassportService(
                new CardService(isoDep),
                PassportService.NormalMaxTranceiveLength,
                PassportService.DefaultMaxBlockSize,
                false,
                false
            );

            // Perform BAC (Basic Access Control)
            var bacKey = new BACKey(documentNumber, dateOfBirth, dateOfExpiry);
            cardService.DoBAC(bacKey);

            // Read DG1 (MRZ data)
            var dg1Stream = cardService.GetInputStream(PassportService.EfDg1);
            var dg1 = new DG1InputStream(dg1Stream);
            var mrzInfo = dg1.MRZInfo;

            // Read DG2 (Face image)
            var dg2Stream = cardService.GetInputStream(PassportService.EfDg2);
            var dg2 = new DG2InputStream(dg2Stream);
            var faceImages = dg2.FaceInfos;

            return new PassportData
            {
                DocumentNumber = mrzInfo.DocumentNumber,
                Name = mrzInfo.PrimaryIdentifier,
                Surname = mrzInfo.SecondaryIdentifier,
                Nationality = mrzInfo.Nationality,
                DateOfBirth = mrzInfo.DateOfBirth,
                FaceImage = faceImages?.FirstOrDefault()?.ImageBytes
            };
        }
        finally
        {
            isoDep?.Close();
        }
    }
}

public class PassportData
{
    public string DocumentNumber { get; set; }
    public string Name { get; set; }
    public string Surname { get; set; }
    public string Nationality { get; set; }
    public string DateOfBirth { get; set; }
    public byte[] FaceImage { get; set; }
}

Required Android Permissions

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="true" />

NFC Intent Filter (for automatic launch)

<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name="android.nfc.action.TECH_DISCOVERED" />
    </intent-filter>
    <meta-data
        android:name="android.nfc.action.TECH_DISCOVERED"
        android:resource="@xml/nfc_tech_filter" />
</activity>

Create Resources/xml/nfc_tech_filter.xml:

<resources>
    <tech-list>
        <tech>android.nfc.tech.IsoDep</tech>
    </tech-list>
</resources>

📚 API Overview

Main Namespaces

• Org.Jmrtd: Core JMRTD classes (PassportService, BACKey, etc.)
• Org.Jmrtd.Lds: Logical Data Structure (DG1-DG16 data groups)
• Org.Jmrtd.Lds.Icao: ICAO-specific implementations
• Org.Jmrtd.Lds.Iso19794: Biometric data formats
• Org.Jmrtd.Cert: Certificate handling (EAC)
• Org.Jmrtd.Protocol: Protocol implementations (BAC, PACE, AA, EAC)

Key Classes

• PassportService: Main service for communicating with eMRTD
• BACKey: Basic Access Control key (derived from MRZ)
• DG1InputStream: Machine Readable Zone (MRZ) data
• DG2InputStream: Face biometric data
• DG3InputStream: Fingerprint biometric data
• DG4InputStream: Iris biometric data
• DG15InputStream: Active Authentication public key

🏗️ Building from Source

Prerequisites

# Install .NET 10 SDK
winget install Microsoft.DotNet.SDK.10

# Verify installation
dotnet --version  # Should show 10.x.x

Build Steps

# Clone the repository
git clone https://github.com/yourusername/jmrtd-binding.git
cd jmrtd-binding

# Restore dependencies
dotnet restore

# Build the project
dotnet build -c Release

# Create NuGet package
dotnet pack -c Release

Build Output

• DLL: bin/Release/net10.0-android/Jmrtd.Binding.dll
• NuGet Package: bin/Release/Jmrtd.Binding.0.8.3.nupkg

⚡ Performance & Best Practices

.NET 10 Optimizations (2025)

1. Trimming Support: This library is marked as trim-safe

   <PublishTrimmed>true</PublishTrimmed>
   

2. AOT Compilation: Compatible with Native AOT

   <PublishAot>true</PublishAot>
   

3. JNI Call Optimization: .NET 10 includes improved JNI marshalling performance

Security Considerations

• ✅ Validate MRZ data before using for BAC
• ✅ Use secure storage for sensitive passport data
• ✅ Clear sensitive data from memory after use
• ✅ Verify document authenticity using Active Authentication
• ⚠️ Never log passport numbers or biometric data
• ⚠️ Comply with GDPR/privacy laws when storing personal data

Common Issues & Solutions

Issue: "Tag was lost" error

Solution: Ensure stable NFC connection, increase timeout values

Issue: BAC authentication fails

Solution: Verify MRZ data is correct (document number, DOB, expiry date)

Issue: OutOfMemoryException when reading biometrics

Solution: Process images in chunks, dispose streams properly

📖 Additional Resources

• JMRTD Official Website
• ICAO Doc 9303 Specifications
• .NET 10 Android Documentation
• .NET MAUI Documentation

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This binding library is released under LGPL 3.0 (same as JMRTD).

The original JMRTD library is developed by the JMRTD team and is licensed under LGPL 3.0.

⚠️ Legal Notice

This library is intended for legitimate use cases such as:

• Identity verification applications
• Border control systems
• Travel document validation
• Research and education

Do not use this library for:

• Unauthorized access to travel documents
• Identity theft or fraud
• Any illegal activities

Users are responsible for compliance with local laws and regulations regarding biometric data processing and privacy.

🔄 Version History

0.8.3 (Current)

• Initial .NET 10 binding release
• Binds JMRTD 0.8.3
• Full support for Android API 21+
• Trim and AOT compatible

📞 Support

For issues specific to this binding:

• Open an issue on GitHub

For JMRTD library questions:

• Visit JMRTD website
• Check JMRTD documentation

Made with ❤️ for the .NET community