cnie-python-tools - GitLite

KO | EN

gitlite — search

#javascript #python #react #ai #golang #go #machine-learning #windows #cli #kubernetes #pytorch #ios #openai #open-source

cnie-python-tools

(★ 95)

Experimental Python toolkit for reading the French National Identity Card (*Carte Nationale d'Identité*, CNI) via a PC/SC **contact** smart card reader, using PACE-CAN authentication and Secure Messaging.

File Explorer

Download Latest Version (.zip)

- __init__.py
- apdu.py
- cli.py
- crypto.py
- datagroups.py
- lds.py
- pace.py
- pcsc.py
- secure_messaging.py
- sod.py
- tlv.py
.gitignore
dump_cnie.py
LICENSE
pyproject.toml
README.md
requirements.txt
uv.lock

# Installation Guide

1. Get the code

git clone https://github.com/hufon/cnie-python-tools

Downloads the entire project code from GitHub to your computer.

cd cnie-python-tools

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

APT (Debian/Ubuntu 계열) Built into Debian/Ubuntu-based Linux distributions.

sudo apt install pcscd libpcsclite-dev swig python3-dev

Installs directly from the APT package repository (Debian/Ubuntu-based).

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install -e .

Installs the Python libraries listed in requirements.txt (or similar).

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# cnie-python-tools

Experimental Python toolkit for reading the French National Identity Card (*Carte Nationale d'Identité*, CNI) via a PC/SC **contact** smart card reader, using PACE-CAN authentication and Secure Messaging.

> **Disclaimer:** This project is for educational and research purposes only. Use it solely on cards you own or have explicit permission to read.

---

## What it does

Modern French CNIs (issued since 2021) embed a chip that stores biographic data and a facial image in the ICAO LDS (Logical Data Structure) format ([ICAO Doc 9303](https://www.icao.int/publications/pages/publication.aspx?docnum=9303)). This toolkit:

- **Authenticates** to the chip using PACE-CAN (Password Authenticated Connection Establishment with the Card Access Number printed on the card), implemented with BrainpoolP256r1 ECDH + AES-CBC-CMAC-256.
- **Establishes** a Secure Messaging (SM) session to protect all subsequent exchanges.
- **Reads and parses** ICAO LDS Data Groups:
  - **DG1** — MRZ (Machine Readable Zone): document number, name, birth date, nationality, expiry date
  - **DG2** — Facial image (JPEG / JPEG 2000)
  - **DG11 / DG12** — Additional personal details (best-effort)
  - **DG13** — France-specific operator data: address, place of birth, height (best-effort)
  - **DG14** — Security infos (OID list)
  - **EF.SOD** — Document Security Object: hash verification of all read DGs
- **Dumps** raw binary EF/DG files and a structured `summary.json`.

---

## What to expect

### Tested readers

| Reader | Interface | Status |
|---|---|---|
| ACS ACR38U | Contact | ✅ Primary supported hardware |
| ACS ACR39U | Contact | ✅ Primary supported hardware |
| HID Omnikey 3021 | Contact | ✅ Primary supported hardware |
| ACS ACR122U | Contactless (NFC) | ✅ Confirmed working (community report) — full PACE-CAN + DG1/DG2/DG11/DG12/DG13/DG14 read successfully |

> **Biometric data cannot be extracted by this tool.**
> DG3 (fingerprints) and DG4 (iris scan) are protected by Extended Access Control (EAC), a PKI-based protocol that requires a government-issued terminal certificate. Without it, the card returns `6982` (security status not satisfied). This tool implements PACE-CAN only and has no EAC support.

- All DGs accessible without EAC are read.
- DG hash verification against EF.SOD is implemented. **Full CMS certificate chain verification is not yet implemented.**
- DG13 parsing is best-effort, based on the field layout observed on French CNI samples — it is not a universal ICAO standard and may vary across card versions.
- Reading uses short APDUs only, in chunks of `0xE0` bytes.

---

## Hardware requirement

A **PC/SC-compatible smart card reader** is required. This includes:

- **Contact readers** (e.g. ACS ACR38U, ACS ACR39U, HID Omnikey 3021) — primary supported hardware.
- **NFC/contactless readers** (e.g. ACS ACR122U) — **confirmed working** for PACE-CAN authentication and DG1/DG2/DG11/DG12/DG13/DG14 reads. Community-tested, not part of the primary test matrix; results may vary depending on card positioning on the antenna.

> **Note:** The French CNI chip supports a dual interface (contact + contactless), so both reader types can access it. Contactless reads may be more sensitive to card placement/timing than contact reads due to RF coupling.

---

## System dependencies

`pyscard` requires a PC/SC stack at the OS level.

**Fedora / RHEL:**
```bash
sudo dnf install pcsc-lite pcsc-lite-ccid pcsc-lite-devel swig python3-devel
sudo systemctl enable --now pcscd
```

**Debian / Ubuntu:**
```bash
sudo apt install pcscd libpcsclite-dev swig python3-dev
sudo systemctl enable --now pcscd
```

---

## Installation

Requires Python ≥ 3.11.

Using [uv](https://github.com/astral-sh/uv) (recommended):

```bash
git clone https://github.com/YOUR_USERNAME/cnie-python-tools.git
cd cnie-python-tools
uv sync
```

Using pip:

```bash
pip install -e .
```

---

## Usage

```bash
uv run cnie-dump --out ./dump
```

The CAN (6-digit number printed on the front of the card, bottom-right) is prompted interactively with hidden input. It can also be passed directly:

```bash
uv run cnie-dump --can 123456 --out ./dump
```

| Option | Description |
|---|---|
| `--can CAN` | Card Access Number (prompted if omitted) |
| `--out DIR` | Output directory (default: `cnie_dump`) |
| `--trace` | Print raw APDU and SM traces |
| `--no-sod` | Skip reading EF.SOD |

---

## Output

| File | Content |
|---|---|
| `ef_com.bin` | Raw EF.COM |
| `ef_sod.bin` | Raw EF.SOD (if read) |
| `dg1.bin` … `dg14.bin` | Raw Data Group files |
| `dg2_photo.jpg` / `.jp2` / `.j2k` | Extracted facial image |
| `summary.json` | Parsed structured data |

`summary.json` includes:

- `DG1` — Parsed MRZ fields
- `DG2` — Photo extraction status
- `DG3` — Present on the card but not readable without EAC (`6982`)
- `DG13` — Best-effort France-specific fields: height, address, place of birth
- `DG14` — List of security OIDs from SecurityInfos
- `SOD` — Hash algorithm, per-DG hash values, and verification result

---

## Project structure

```
cnie/
├── pcsc.py              # PC/SC transport layer
├── pace.py              # PACE-CAN (BrainpoolP256r1 ECDH + AES-CBC-CMAC-256)
├── secure_messaging.py  # SM session state, DO87/DO97/DO99/DO8E wrapping/unwrapping
├── lds.py               # AID selection, EF.COM, EF.SOD, resilient DG reading
├── datagroups.py        # DG1/DG2/DG11–DG14 parsers
├── sod.py               # EF.SOD hash extraction and DG hash verification
├── apdu.py              # APDU helpers
├── crypto.py            # Cryptographic primitives
└── tlv.py               # BER-TLV parser
```

---

## Known limitations

- **No EAC support** — DG3 (fingerprints) and DG4 (iris scan) are protected by EAC (Extended Access Control), a PKI-based protocol requiring a government-issued terminal certificate. These DGs always return `6982` and **cannot be read by this tool**.
- **No CMS signature verification** — EF.SOD embeds a CMS-signed structure with a certificate chain up to the CSCA (Country Signing Certificate Authority). Full chain verification is not yet implemented.
- **DG13 is France-specific** — Field interpretation is based on observed samples and may be inaccurate for other card generations.
- **Primarily tested with contact readers** — NFC/contactless access has been confirmed to work with the ACS ACR122U, but is not part of the primary test matrix. Behavior with other contactless readers is unverified.
- **Short APDUs only** — APDU command chaining is not used.

---

## References

- [ICAO Doc 9303 — Machine Readable Travel Documents](https://www.icao.int/publications/pages/publication.aspx?docnum=9303)
- [BSI TR-03110 — Advanced Security Mechanisms for MRTD (PACE)](https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/Technische-Richtlinien/TR-nach-Thema-sortiert/tr03110/TR-03110_node.html)

---

## License

MIT — see [LICENSE](LICENSE).