pythonbeid 0.1.0__tar.gz → 0.2.0__tar.gz

pythonbeid-0.2.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: pythonbeid
+Version: 0.2.0
+Summary: Un module pour lire les informations des cartes d'identité belges
+Author-email: Fabien Toune <fabien.toune@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Lapin-Blanc/pythonbeid
+Project-URL: Bug Tracker, https://github.com/Lapin-Blanc/pythonbeid/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyscard
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+
+# PythonBEID
+
+PythonBEID est un module Python pour lire les informations essentielles des cartes d'identité belge à l'aide d'un lecteur de cartes PC/SC et de la bibliothèque `pyscard`.
+
+## Installation
+
+```bash
+pip install pythonbeid
+```
+
+## Utilisation
+
+```python
+from pythonbeid import CardReader, NoReaderError, NoCardError
+
+try:
+    with CardReader() as cr:          # context manager — ferme proprement la connexion
+        info = cr.read_informations(photo=False)
+        print(info["last_name"])      # Smith
+        print(info["birth_date"])     # datetime(1990, 1, 1)
+except NoReaderError:
+    print("Aucun lecteur de carte détecté.")
+except NoCardError:
+    print("Aucune carte dans le lecteur.")
+```
+
+Si plusieurs lecteurs sont connectés, précisez l'index :
+
+```python
+with CardReader(reader_index=1) as cr:
+    info = cr.read_informations()
+```
+
+### Champs retournés par `read_informations()`
+
+| Clé | Type | Description |
+|---|---|---|
+| `card_number` | str | Numéro de la carte |
+| `validity_start` | datetime | Date début de validité |
+| `validity_end` | datetime | Date fin de validité |
+| `issuing_municipality` | str | Commune de délivrance |
+| `national_number` | str | Numéro national |
+| `last_name` | str | Nom de famille |
+| `first_names` | str | Prénom(s) |
+| `suffix` | str | Suffixe de nom |
+| `nationality` | str | Nationalité |
+| `birth_place` | str | Lieu de naissance |
+| `birth_date` | datetime | Date de naissance |
+| `sex` | str | Sexe |
+| `address` | str | Adresse |
+| `postal_code` | str | Code postal |
+| `city` | str | Localité |
+| `photo` | str | Photo en base64 (si `photo=True`) |
+
+### Activer les logs
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Dépendances
+
+- `pyscard`
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest                          # tous les tests (matériel skippé si absent)
+pytest tests/test_parser.py     # tests sans matériel uniquement
+```
+
+## Contribuer
+
+Les contributions et améliorations sont les bienvenues !
+
+## Licence
+
+Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails.

pythonbeid-0.2.0/README.md

@@ -0,0 +1,81 @@
+
+# PythonBEID
+
+PythonBEID est un module Python pour lire les informations essentielles des cartes d'identité belge à l'aide d'un lecteur de cartes PC/SC et de la bibliothèque `pyscard`.
+
+## Installation
+
+```bash
+pip install pythonbeid
+```
+
+## Utilisation
+
+```python
+from pythonbeid import CardReader, NoReaderError, NoCardError
+
+try:
+    with CardReader() as cr:          # context manager — ferme proprement la connexion
+        info = cr.read_informations(photo=False)
+        print(info["last_name"])      # Smith
+        print(info["birth_date"])     # datetime(1990, 1, 1)
+except NoReaderError:
+    print("Aucun lecteur de carte détecté.")
+except NoCardError:
+    print("Aucune carte dans le lecteur.")
+```
+
+Si plusieurs lecteurs sont connectés, précisez l'index :
+
+```python
+with CardReader(reader_index=1) as cr:
+    info = cr.read_informations()
+```
+
+### Champs retournés par `read_informations()`
+
+| Clé | Type | Description |
+|---|---|---|
+| `card_number` | str | Numéro de la carte |
+| `validity_start` | datetime | Date début de validité |
+| `validity_end` | datetime | Date fin de validité |
+| `issuing_municipality` | str | Commune de délivrance |
+| `national_number` | str | Numéro national |
+| `last_name` | str | Nom de famille |
+| `first_names` | str | Prénom(s) |
+| `suffix` | str | Suffixe de nom |
+| `nationality` | str | Nationalité |
+| `birth_place` | str | Lieu de naissance |
+| `birth_date` | datetime | Date de naissance |
+| `sex` | str | Sexe |
+| `address` | str | Adresse |
+| `postal_code` | str | Code postal |
+| `city` | str | Localité |
+| `photo` | str | Photo en base64 (si `photo=True`) |
+
+### Activer les logs
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Dépendances
+
+- `pyscard`
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest                          # tous les tests (matériel skippé si absent)
+pytest tests/test_parser.py     # tests sans matériel uniquement
+```
+
+## Contribuer
+
+Les contributions et améliorations sont les bienvenues !
+
+## Licence
+
+Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails.

pythonbeid-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pythonbeid"
+version = "0.2.0"
+description = "Un module pour lire les informations des cartes d'identité belges"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Fabien Toune", email = "fabien.toune@gmail.com" }]
+requires-python = ">=3.9"
+dependencies = ["pyscard"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/Lapin-Blanc/pythonbeid"
+"Bug Tracker" = "https://github.com/Lapin-Blanc/pythonbeid/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "build", "twine"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pythonbeid-0.2.0/pythonbeid/__init__.py

@@ -0,0 +1,12 @@
+"""pythonbeid — read information from Belgian eID cards."""
+
+from .card_reader import CardReader
+from .exceptions import APDUError, CardCommunicationError, NoCardError, NoReaderError
+
+__all__ = [
+    "CardReader",
+    "NoReaderError",
+    "NoCardError",
+    "CardCommunicationError",
+    "APDUError",
+]

pythonbeid-0.2.0/pythonbeid/card_reader.py

@@ -0,0 +1,256 @@
+"""Belgian eID card reader.
+
+Reads personal data, address and optionally the photo from a Belgian
+electronic identity card via a PC/SC-compatible smart card reader.
+
+Dependencies: pyscard (python-smartcard)
+
+Usage::
+
+    from pythonbeid import CardReader
+
+    with CardReader() as cr:
+        info = cr.read_informations(photo=False)
+        print(info["last_name"])
+"""
+import base64
+import logging
+from datetime import datetime
+from typing import Any
+
+from smartcard.Exceptions import CardConnectionException, NoCardException
+from smartcard.System import readers
+
+from .exceptions import APDUError, CardCommunicationError, NoCardError, NoReaderError
+from .parser import parse_french_date, parse_tlv
+
+logger = logging.getLogger(__name__)
+
+# ── File identifiers (path on the card) ──────────────────────────────────────
+_FILE_ID = [0x3F, 0x00, 0xDF, 0x01, 0x40, 0x31]      # personal identity data
+_FILE_ADDRESS = [0x3F, 0x00, 0xDF, 0x01, 0x40, 0x33]  # address data
+_FILE_PHOTO = [0x3F, 0x00, 0xDF, 0x01, 0x40, 0x35]    # photo data
+
+# ISO 7816-4: Le=0x00 in a short APDU means "expect up to 256 bytes".
+_LE_MAX = 0x00
+
+# ── Status words that are handled in-band ──────────────────────────────────
+_SW_OK = 0x90           # Normal completion
+_SW_MORE_DATA = 0x61    # More data available (GET RESPONSE with SW2 bytes)
+_SW_WRONG_LE = 0x6C     # Wrong Le: use SW2 as exact length
+
+
+class CardReader:
+    """Read information from a Belgian eID card.
+
+    Parameters
+    ----------
+    reader_index:
+        Index of the PC/SC reader to use when multiple readers are connected.
+        Defaults to 0 (first available reader).
+
+    Examples
+    --------
+    Using as a context manager (recommended)::
+
+        with CardReader() as cr:
+            data = cr.read_informations()
+
+    Or manually::
+
+        cr = CardReader()
+        try:
+            data = cr.read_informations()
+        finally:
+            cr.close()
+    """
+
+    def __init__(self, reader_index: int = 0) -> None:
+        available = readers()
+        if not available:
+            raise NoReaderError("No smart card reader detected")
+        if reader_index >= len(available):
+            raise NoReaderError(
+                f"Reader index {reader_index} out of range "
+                f"({len(available)} reader(s) available)"
+            )
+        reader = available[reader_index]
+        logger.debug("Using reader: %s", reader)
+        try:
+            self._cnx = reader.createConnection()
+            self._cnx.connect()
+        except NoCardException:
+            raise NoCardError(f"No card in reader '{reader}'")
+        except CardConnectionException as exc:
+            raise CardCommunicationError(f"Connection error on '{reader}': {exc}") from exc
+        logger.debug("Connected to card via '%s'", reader)
+
+    # ── Context manager ───────────────────────────────────────────────────
+
+    def __enter__(self) -> "CardReader":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Disconnect from the card and release the reader."""
+        try:
+            self._cnx.disconnect()
+            logger.debug("Disconnected from card")
+        except Exception:
+            pass  # Ignore errors on cleanup
+
+    # ── Low-level APDU transport ──────────────────────────────────────────
+
+    def _send_apdu(self, apdu: list[int]) -> tuple[list[int], int, int]:
+        """Transmit one APDU and return ``(data, SW1, SW2)``.
+
+        Raises
+        ------
+        APDUError
+            If the card returns an unexpected status word (i.e. not 0x90,
+            0x61, or 0x6C).
+        """
+        response, sw1, sw2 = self._cnx.transmit(apdu)
+        logger.debug("APDU %s → SW=%02X%02X  data(%d)=%s",
+                     [f"{b:02X}" for b in apdu], sw1, sw2, len(response),
+                     [f"{b:02X}" for b in response[:8]])
+        if sw1 not in (_SW_OK, _SW_MORE_DATA, _SW_WRONG_LE):
+            raise APDUError(sw1, sw2,
+                            f"Unexpected status SW={sw1:02X}{sw2:02X} "
+                            f"for APDU {[hex(b) for b in apdu[:4]]}")
+        return response, sw1, sw2
+
+    # ── File access helpers ───────────────────────────────────────────────
+
+    def _select_file(self, file_id: list[int]) -> None:
+        """Send a SELECT command for *file_id* (no response expected)."""
+        cmd = [0x00, 0xA4, 0x08, 0x0C, len(file_id)] + file_id
+        _, sw1, sw2 = self._send_apdu(cmd)
+        if sw1 != _SW_OK:
+            raise APDUError(sw1, sw2, f"SELECT failed for file {[hex(b) for b in file_id]}")
+        logger.debug("Selected file %s", [f"{b:02X}" for b in file_id])
+
+    def _read_binary(self, p1: int, p2: int, le: int) -> tuple[list[int], int, int]:
+        """Send a READ BINARY command and handle Le mismatch (0x6C)."""
+        cmd = [0x00, 0xB0, p1, p2, le]
+        data, sw1, sw2 = self._send_apdu(cmd)
+        if sw1 == _SW_WRONG_LE:
+            # Card tells us the exact length: re-issue with SW2 as Le.
+            logger.debug("RE-READ BINARY with Le=%d (was %d)", sw2, le)
+            cmd[-1] = sw2
+            data, sw1, sw2 = self._send_apdu(cmd)
+        return data, sw1, sw2
+
+    def _read_data(self, file_id: list[int]) -> list[int]:
+        """Select *file_id* and read its content (up to 256 bytes)."""
+        self._select_file(file_id)
+        data, sw1, sw2 = self._read_binary(0x00, 0x00, _LE_MAX)
+        logger.debug("Read %d bytes from file %s, SW=%02X%02X",
+                     len(data), [f"{b:02X}" for b in file_id], sw1, sw2)
+        return data
+
+    def _read_photo(self) -> bytearray:
+        """Read the complete photo file in 256-byte chunks.
+
+        The photo file is typically larger than 256 bytes so it must be
+        read with successive READ BINARY commands using an incrementing
+        offset (P1 = high byte, P2 = low byte of a 15-bit offset).
+        """
+        self._select_file(_FILE_PHOTO)
+        photo_bytes: list[int] = []
+        # Offset advances by 256 bytes on each iteration.
+        # P1 holds the high byte of the byte offset (offset >> 8),
+        # P2 holds the low byte (offset & 0xFF).
+        # Starting with P1=0, P2=0 and incrementing P1 by 1 each time
+        # moves the window by 256 bytes per step.
+        p1 = 0
+        while True:
+            data, sw1, sw2 = self._read_binary(p1, 0x00, _LE_MAX)
+            if sw1 == _SW_OK:
+                photo_bytes.extend(data)
+                if len(data) < 256:
+                    # Received fewer bytes than requested → end of file.
+                    break
+                p1 += 1
+            elif sw1 == _SW_WRONG_LE:
+                # _read_binary already retried with the correct Le,
+                # so if we still get here something went wrong.
+                logger.warning("Unexpected 0x6C after retry at p1=%d", p1)
+                photo_bytes.extend(data)
+                break
+            else:
+                # Any other status (e.g. 0x6282 end-of-file) ends the loop.
+                logger.debug("Photo read ended at p1=%d, SW=%02X%02X", p1, sw1, sw2)
+                break
+        logger.debug("Photo: %d bytes total", len(photo_bytes))
+        return bytearray(photo_bytes)
+
+    # ── Public API ────────────────────────────────────────────────────────
+
+    def read_informations(self, photo: bool = False) -> dict[str, Any]:
+        """Read and return all information from the card.
+
+        Parameters
+        ----------
+        photo:
+            When ``True`` the card photo is read and included in the
+            returned dictionary as a base-64 encoded string.
+
+        Returns
+        -------
+        dict
+            Keys: ``card_number``, ``validity_start``, ``validity_end``,
+            ``issuing_municipality``, ``national_number``, ``last_name``,
+            ``first_names``, ``suffix``, ``nationality``, ``birth_place``,
+            ``birth_date``, ``sex``, ``address``, ``postal_code``,
+            ``city``, and optionally ``photo``.
+        """
+        # ── Identity file ────────────────────────────────────────────────
+        id_data = self._read_data(_FILE_ID)
+        id_fields = parse_tlv(id_data, 13)  # tags 1–13 (tag 2 / index 1 unused)
+
+        informations: dict[str, Any] = {
+            "card_number":          id_fields[0],
+            # id_fields[1] is the chip serial number — not exposed in the API
+            "validity_start":       datetime.strptime(id_fields[2], "%d.%m.%Y"),
+            "validity_end":         datetime.strptime(id_fields[3], "%d.%m.%Y"),
+            "issuing_municipality": id_fields[4],
+            "national_number":      id_fields[5],
+            "last_name":            id_fields[6],
+            "first_names":          id_fields[7],
+            "suffix":               id_fields[8],
+            "nationality":          id_fields[9],
+            "birth_place":          id_fields[10],
+            "birth_date":           parse_french_date(id_fields[11]),
+            "sex":                  id_fields[12],
+        }
+
+        # ── Address file ─────────────────────────────────────────────────
+        addr_data = self._read_data(_FILE_ADDRESS)
+        addr_fields = parse_tlv(addr_data, 3)
+
+        informations["address"]     = addr_fields[0]
+        informations["postal_code"] = addr_fields[1]
+        informations["city"]        = addr_fields[2]
+
+        # ── Photo (optional) ─────────────────────────────────────────────
+        if photo:
+            photo_bytes = self._read_photo()
+            informations["photo"] = base64.b64encode(photo_bytes).decode("ascii")
+
+        # Mirror every key as an instance attribute for convenience.
+        for key, value in informations.items():
+            setattr(self, key, value)
+
+        return informations
+
+
+if __name__ == "__main__":
+    import logging
+    from pprint import pprint
+
+    logging.basicConfig(level=logging.WARNING)
+    with CardReader() as cr:
+        pprint(cr.read_informations(photo=False))

pythonbeid-0.2.0/pythonbeid/exceptions.py

@@ -0,0 +1,30 @@
+"""Custom exceptions for pythonbeid."""
+
+
+class NoReaderError(RuntimeError):
+    """Raised when no smart card reader is detected."""
+
+
+class NoCardError(RuntimeError):
+    """Raised when a reader is present but no card is inserted."""
+
+
+class CardCommunicationError(RuntimeError):
+    """Raised on a general card communication failure."""
+
+
+class APDUError(CardCommunicationError):
+    """Raised when an APDU command returns an unexpected status word.
+
+    Attributes
+    ----------
+    sw1 : int
+        First status byte (SW1).
+    sw2 : int
+        Second status byte (SW2).
+    """
+
+    def __init__(self, sw1: int, sw2: int, message: str = "") -> None:
+        self.sw1 = sw1
+        self.sw2 = sw2
+        super().__init__(message or f"Unexpected APDU status: SW={sw1:02X}{sw2:02X}")

pythonbeid-0.2.0/pythonbeid/parser.py

@@ -0,0 +1,89 @@
+"""Pure parsing functions for Belgian eID card data.
+
+These functions have no I/O dependencies and can be tested without hardware.
+"""
+from datetime import datetime
+
+# French month abbreviations as found on Belgian eID cards.
+_MONTH_MAP: dict[str, str] = {
+    "JANV": "01", "JAN": "01",
+    "FEVR": "02", "FEV": "02",
+    "MARS": "03", "MAR": "03",
+    "AVRI": "04", "AVR": "04",
+    "MAI":  "05",
+    "JUIN": "06",
+    "JUIL": "07",
+    "AOUT": "08", "AOU": "08",
+    "SEPT": "09", "SEP": "09",
+    "OCTO": "10", "OCT": "10",
+    "NOVE": "11", "NOV": "11",
+    "DECE": "12", "DEC": "12",
+}
+
+
+def parse_tlv(data: list[int], num_fields: int) -> list[str]:
+    """Parse a TLV-encoded buffer from a Belgian eID card.
+
+    Each record has the format: [tag: 1 byte] [length: 1 byte] [value: length bytes].
+    Parsing stops once *num_fields* records have been extracted or the buffer
+    is exhausted (whichever comes first).
+
+    Parameters
+    ----------
+    data:
+        Raw bytes received from the card (list of ints, 0–255).
+    num_fields:
+        Maximum number of fields to extract.
+
+    Returns
+    -------
+    list[str]
+        Decoded string values; an empty string is used for any field that
+        cannot be decoded as UTF-8.
+    """
+    idx = 0
+    fields: list[str] = []
+    while len(fields) < num_fields:
+        # Need at least 2 bytes for tag + length.
+        if idx + 1 >= len(data):
+            break
+        # tag byte (idx) — not used for value extraction
+        idx += 1
+        length = data[idx]
+        idx += 1
+        # Guard against a truncated buffer.
+        if idx + length > len(data):
+            break
+        raw = bytes(data[idx: idx + length])
+        idx += length
+        try:
+            fields.append(raw.decode("utf-8"))
+        except UnicodeDecodeError:
+            fields.append("")
+    return fields
+
+
+def parse_french_date(date_str: str) -> datetime:
+    """Parse a French date string as printed on Belgian eID cards.
+
+    Expected format: ``DD MON YYYY`` where *MON* is a French month
+    abbreviation (e.g. ``"15 JANV 2000"`` or ``"03 MAR 1985"``).
+
+    Unknown month abbreviations fall back to January ("01").
+
+    Parameters
+    ----------
+    date_str:
+        Date string to parse.
+
+    Returns
+    -------
+    datetime
+        Parsed date (time component is midnight, no timezone).
+    """
+    parts = date_str.split()
+    if len(parts) != 3:
+        raise ValueError(f"Unexpected date format: {date_str!r}")
+    day, month_abbr, year = parts
+    month = _MONTH_MAP.get(month_abbr.upper(), "01")
+    return datetime.strptime(f"{day}/{month}/{year}", "%d/%m/%Y")