🌐 Language: English · ไทย

libthai-idcard

A Rust library for reading Thai National ID smart cards via PC/SC smart card readers, with C, C++, Go, Java, Kotlin, JavaScript, Python, and Ruby usage examples.

Overview

Thai National ID smart cards store citizen identification data, a JPEG face photo, NHSO (National Health Security Office) insurance information, and a laser-engraved card serial number. This library handles the low-level APDU communication, TIS-620 (Thai) text decoding, and Buddhist-to-Gregorian date conversion, exposing the data through a clean multi-language API.

Features

• ✅ Read citizen ID, name (Thai & English), date of birth, gender
• ✅ Read registered address (parsed into components)
• ✅ Read card issuer, issue date, expiry date
• ✅ Read JPEG face photo (returned as base64)
• ✅ Read laser-engraved card serial number
• ✅ Read NHSO insurance data (main/sub hospitals, coverage dates, etc.)
• ✅ Buddhist year → Gregorian calendar conversion
• ✅ TIS-620 (Windows-874) Thai text decoding
• ✅ Auto-detect card reader or specify by name
• ✅ Daemon mode for continuous card monitoring
• ✅ C usage example (dynamic loading or link-time)
• ✅ C++ usage example (via dlopen/LoadLibrary)
• ✅ Go usage example (via cgo)
• ✅ Java usage example (via JNA)
• ✅ Kotlin usage example (via JNA)
• ✅ JavaScript usage example (via koffi)
• ✅ Python usage example (via ctypes)
• ✅ Ruby usage example (via fiddle)

Requirements

• Hardware: A PC/SC-compatible smart card reader and a Thai National ID card
• Software: PC/SC Lite (pcsclite) — installed by default on macOS and most Linux distributions
  • macOS: Built-in (PCSC.framework)
  • Linux: sudo apt install libpcsclite-dev (Debian/Ubuntu) or sudo dnf install pcsc-lite-devel (Fedora)
  • Windows: Winscard (built-in)

Usage

Rust

use thaiidcard::{SmartCard, Options};

let card = SmartCard::new();
let data = card.read(None, &Options::default()).unwrap();

let personal = data.personal.unwrap();
println!("Name: {}", personal.name.full_name);
println!("CID: {}", personal.cid);
println!("DOB: {}", personal.dob);

Or with a specific reader and extra data sections:

use thaiidcard::{SmartCard, Options};

let opts = Options {
    show_nhso_data: true,
    show_laser_data: true,
    show_face_image: true,
    ..Default::default()
};

let card = SmartCard::new();
let data = card.read(Some("Identive USB Reader"), &opts).unwrap();

See examples/rust_usage.rs for a complete example.

C

A C usage example is available at examples/c_usage.c. It demonstrates both dynamic loading (dlopen/dlsym) and compile-time linking against the shared library.

# Dynamic loading (no linker flags)
cc -o c_usage examples/c_usage.c -ldl
./c_usage

# Compile-time linking
cc -o c_usage examples/c_usage.c -Ltarget/debug -lthaiidcard \
   -lpcsclite -Wl,-rpath,target/debug
./c_usage

C++

A C++ usage example is available at examples/cpp_usage.cpp. It uses RAII wrappers and C++17 features to load the shared library and read card data.

# macOS / Linux:
g++ -std=c++17 -o cpp_usage examples/cpp_usage.cpp -ldl
./cpp_usage

# Windows (MinGW):
g++ -std=c++17 -o cpp_usage.exe examples/cpp_usage.cpp
./cpp_usage

Go

A Go usage example is available at examples/go_usage.go. It uses cgo to load the shared library via dlopen and read card data.

go run examples/go_usage.go

Java

A Java usage example is available at examples/java_usage.java. It uses JNA (Java Native Access) to call the shared library functions.

# With jbang (auto-downloads JNA):
jbang examples/java_usage.java

# Or compile & run manually (download jna.jar first):
javac -cp jna.jar examples/java_usage.java
java -cp .:jna.jar java_usage

Kotlin

A Kotlin usage example is available at examples/kotlin_usage.kt. It uses JNA (Java Native Access) to call the shared library functions.

# With jbang (auto-downloads JNA):
jbang examples/kotlin_usage.kt

# Or compile & run manually (download jna.jar first):
kotlinc -cp jna.jar examples/kotlin_usage.kt
kotlin -cp .:jna.jar kotlin_usageKt

JavaScript

A JavaScript usage example is available at examples/js_usage.js. It uses koffi (a modern FFI library for Node.js) to call the shared library functions.

npm install koffi
node examples/js_usage.js

Python

A Python usage example is available at examples/python_usage.py. It uses ctypes to load the shared library and read card data.

python3 examples/python_usage.py

Ruby

A Ruby usage example is available at examples/ruby_usage.rb. It uses fiddle (Ruby's built-in FFI library) to load the shared library and read card data.

ruby examples/ruby_usage.rb

Building

# Build all Rust targets (library + examples)
make build

# Build only the native shared library (.dylib/.so/.dll)
make shared

# Generate C header file (requires cbindgen)
make headers

# Run the Rust usage example
make example

# Run the C example
make c-example

# Run the C++ example
make cpp-example

# Run the Go example
make go-example

# Run the Java example
make java-example

# Run the Kotlin example
make kotlin-example

# Run the JavaScript example
make js-example

# Run the Python example
make python-example

# Run the Ruby example
make ruby-example

Pre-built Binaries

Pre-built shared libraries are available on the GitHub Releases page for the following platforms:

Cross-compilation

All cross-compilation targets use Docker (except build-win-native* which require a locally installed mingw-w64). macOS builds use osxcross to provide the Apple SDK and toolchain inside the Linux-based Docker image.

# Build Linux .so via Docker (x86_64)
make build-linux

# Build Linux .so via Docker (ARM64)
make build-linux-arm64

# Build macOS .dylib via Docker using osxcross (Intel)
make build-mac-x64

# Build macOS .dylib via Docker using osxcross (Apple Silicon)
make build-mac

# Build Windows DLL via Docker (x86_64)
make build-win

# Build Windows DLL natively (x86_64, requires mingw-w64)
make build-win-native

# Build Windows DLL natively in release mode
make build-win-native-release

Note: Windows ARM64 and Linux ARM64 builds are also available as pre-built binaries from GitHub Releases, built natively on GitHub Actions runners.

Or directly with Cargo:

cargo build --release
cargo build --lib # shared library only

Data Model

CardData
├── personal: Personal
│   ├── cid              — 13-digit citizen ID
│   ├── name             — Full name in Thai (with prefix, first, middle, last)
│   ├── name_en          — Full name in English
│   ├── dob              — Date of birth (YYYY-MM-DD)
│   ├── gender           — M or F
│   ├── card_issuer      — Issuing authority
│   ├── issue_date       — Card issue date (YYYY-MM-DD)
│   ├── expire_date      — Card expiry date (YYYY-MM-DD)
│   ├── address          — Registered address (parsed into components)
│   └── face_image       — Face photo as base64 JPEG
├── card: Card
│   └── laser_id         — Laser-engraved serial number
└── nhso: Nhso
      ├── main_inscl     — Main insurance scheme
      ├── sub_inscl      — Sub insurance scheme
      ├── main_hospital  — Primary hospital
      ├── sub_hospital   — Secondary hospital
      ├── paid_type      — Payment type
      ├── issue_date     — NHSO coverage start date
      ├── expire_date    — NHSO coverage end date
      ├── update_date    — Last update date
      └── change_hospital_amount — Hospital change count

Project Structure

├── Cargo.toml
├── Makefile
├── Dockerfile.build       — Cross-compilation Docker image (osxcross)
├── src/
│   ├── lib.rs             — Main API (SmartCard, start_daemon)
│   ├── ffi.rs             — C-compatible FFI exports
│   ├── model.rs           — Data types & parsing helpers
│   ├── apdu.rs            — APDU command constants
│   ├── reader.rs          — Low-level PC/SC operations
│   ├── personal.rs        — Personal data reader
│   ├── nhso.rs            — NHSO data reader
│   ├── laser.rs           — Laser ID reader
│   └── options.rs         — Configuration options
└── examples/
    ├── rust_usage.rs      — Rust usage example
    ├── c_usage.c          — C usage example
    ├── cpp_usage.cpp      — C++ usage example
    ├── go_usage.go        — Go usage example
    ├── java_usage.java    — Java usage example
    ├── kotlin_usage.kt    — Kotlin usage example
    ├── js_usage.js        — JavaScript usage example
    ├── python_usage.py    — Python usage example
    └── ruby_usage.rb      — Ruby usage example

References

• Thai National ID Card APDU Specification
• go-thai-smartcard NHSO APDU Implementation

License

Licensed under either of:

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.