qkdsec 0.2.0__py3-none-any.whl

qkdsec/__init__.py

@@ -0,0 +1,14 @@
+"""qkdsec — a developer toolkit for Quantum Key Distribution.
+
+Subpackages:
+    qkdsec.proofs   — numerical security proofs (key-rate lower bounds)
+    qkdsec.sim      — BB84 simulator (Qiskit + classical backends)
+    qkdsec.client   — ETSI GS QKD 014 REST client
+
+Each subpackage may require optional dependencies. See README.md for install
+options (e.g., ``pip install qkdsec[proofs]``).
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

qkdsec/_cli.py

@@ -0,0 +1,287 @@
+"""Top-level ``qkdsec`` command-line interface.
+
+Requires the ``cli`` (or ``doctor``) extra: ``pip install qkdsec[cli]``.
+
+Subcommands::
+
+    qkdsec doctor <base_url> [--slave-sae-id SAE] [--cert PATH] [--key PATH]
+        [--ca-cert PATH] [--format text|json|html] [--output FILE]
+        [--no-consume] [--samples N]
+
+    qkdsec status <base_url> <slave_sae_id> [--cert ...] [--key ...] [--ca-cert ...]
+
+    qkdsec keys get <base_url> <slave_sae_id>
+        [--number N] [--size S] [--cert ...] [--key ...] [--ca-cert ...]
+
+    qkdsec keys retrieve <base_url> <slave_sae_id> <key_id>...
+        [--cert ...] [--key ...] [--ca-cert ...]
+
+    qkdsec version
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    import typer
+    from rich.console import Console
+except ImportError as e:
+    raise ImportError(
+        "qkdsec CLI requires extra dependencies. "
+        "Install with: pip install qkdsec[cli]"
+    ) from e
+
+from . import __version__
+from .client import ETSI014Client
+from .client.errors import KMEError
+
+app = typer.Typer(
+    name="qkdsec",
+    help="ETSI GS QKD 014 toolkit — KME probe, status, and key fetch.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+keys_app = typer.Typer(
+    help="Fetch keys from a KME (enc_keys / dec_keys).",
+    no_args_is_help=True,
+)
+app.add_typer(keys_app, name="keys")
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+# ── Shared options ────────────────────────────────────────────────────────
+
+
+def _build_client(
+    base_url: str,
+    cert: Optional[Path],
+    key: Optional[Path],
+    ca_cert: Optional[Path],
+    insecure: bool,
+    timeout: float,
+) -> ETSI014Client:
+    if insecure:
+        verify: bool | str = False
+    elif ca_cert is not None:
+        verify = str(ca_cert)
+    else:
+        verify = True
+
+    client_cert: str | tuple[str, str] | None
+    if cert and key:
+        client_cert = (str(cert), str(key))
+    elif cert:
+        client_cert = str(cert)
+    else:
+        client_cert = None
+
+    return ETSI014Client(
+        base_url,
+        client_cert=client_cert,
+        verify=verify,
+        timeout=timeout,
+    )
+
+
+# ── doctor ────────────────────────────────────────────────────────────────
+
+
+@app.command(help="Probe a KME for ETSI GS QKD 014 conformance.")
+def doctor(
+    base_url: str = typer.Argument(..., help="KME base URL (e.g., https://kme.example.com)."),
+    slave_sae_id: str = typer.Option(
+        "sae-bob", "--slave-sae-id", "-s",
+        help="The slave SAE ID to probe against.",
+    ),
+    cert: Optional[Path] = typer.Option(
+        None, "--cert", help="Client certificate (PEM)."),
+    key: Optional[Path] = typer.Option(
+        None, "--key", help="Client private key (PEM)."),
+    ca_cert: Optional[Path] = typer.Option(
+        None, "--ca-cert", help="Path to CA certificate for TLS verification."),
+    insecure: bool = typer.Option(
+        False, "--insecure", help="Disable TLS verification (NOT for production)."),
+    fmt: str = typer.Option(
+        "text", "--format", "-f",
+        help="Output format: text, json, html.",
+    ),
+    output: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write report to file instead of stdout."),
+    no_consume: bool = typer.Option(
+        False, "--no-consume",
+        help="Skip probes that consume real keys.",
+    ),
+    samples: int = typer.Option(
+        5, "--samples", help="Latency probe sample count."),
+    timeout: float = typer.Option(
+        30.0, "--timeout", help="Per-request HTTP timeout in seconds."),
+) -> None:
+    from .doctor import format_html, format_json, format_text, run_all
+
+    if fmt not in ("text", "json", "html"):
+        err_console.print(f"[red]Invalid format: {fmt}[/]")
+        raise typer.Exit(2)
+
+    client = _build_client(base_url, cert, key, ca_cert, insecure, timeout)
+    try:
+        report = run_all(
+            client,
+            slave_sae_id=slave_sae_id,
+            consume_keys=not no_consume,
+            latency_samples=samples,
+        )
+    finally:
+        client.close()
+
+    if fmt == "text":
+        rendered = format_text(report)
+    elif fmt == "json":
+        rendered = format_json(report)
+    else:
+        rendered = format_html(report)
+
+    if output:
+        output.write_text(rendered)
+        err_console.print(f"[dim]Report written to {output}[/]")
+    else:
+        # For text format we already have terminal control codes; print raw.
+        # For json/html, write plainly via sys.stdout.
+        if fmt == "text":
+            sys.stdout.write(rendered)
+            if not rendered.endswith("\n"):
+                sys.stdout.write("\n")
+        else:
+            print(rendered)
+
+    raise typer.Exit(0 if report.passed else 1)
+
+
+# ── status ────────────────────────────────────────────────────────────────
+
+
+@app.command(help="Fetch KME status for a slave SAE.")
+def status(
+    base_url: str = typer.Argument(...),
+    slave_sae_id: str = typer.Argument(...),
+    cert: Optional[Path] = typer.Option(None, "--cert"),
+    key: Optional[Path] = typer.Option(None, "--key"),
+    ca_cert: Optional[Path] = typer.Option(None, "--ca-cert"),
+    insecure: bool = typer.Option(False, "--insecure"),
+    timeout: float = typer.Option(30.0, "--timeout"),
+    as_json: bool = typer.Option(False, "--json", help="Emit raw JSON."),
+) -> None:
+    client = _build_client(base_url, cert, key, ca_cert, insecure, timeout)
+    try:
+        s = client.status(slave_sae_id)
+    except KMEError as e:
+        err_console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+    payload = {
+        "source_kme_id": s.source_kme_id,
+        "target_kme_id": s.target_kme_id,
+        "master_sae_id": s.master_sae_id,
+        "slave_sae_id": s.slave_sae_id,
+        "key_size": s.key_size,
+        "stored_key_count": s.stored_key_count,
+        "max_key_count": s.max_key_count,
+        "max_key_per_request": s.max_key_per_request,
+        "max_key_size": s.max_key_size,
+        "min_key_size": s.min_key_size,
+        "max_sae_id_count": s.max_sae_id_count,
+        "status_extension": s.status_extension,
+    }
+    if as_json:
+        print(json.dumps(payload, indent=2))
+    else:
+        for k, v in payload.items():
+            console.print(f"  [bold]{k}[/]: {v}")
+
+
+# ── keys get / retrieve ───────────────────────────────────────────────────
+
+
+@keys_app.command("get", help="Master SAE: fetch fresh keys via enc_keys.")
+def keys_get(
+    base_url: str = typer.Argument(...),
+    slave_sae_id: str = typer.Argument(...),
+    number: int = typer.Option(1, "--number", "-n"),
+    size: int = typer.Option(256, "--size"),
+    method: str = typer.Option("GET", "--method"),
+    cert: Optional[Path] = typer.Option(None, "--cert"),
+    key: Optional[Path] = typer.Option(None, "--key"),
+    ca_cert: Optional[Path] = typer.Option(None, "--ca-cert"),
+    insecure: bool = typer.Option(False, "--insecure"),
+    timeout: float = typer.Option(30.0, "--timeout"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    client = _build_client(base_url, cert, key, ca_cert, insecure, timeout)
+    try:
+        keys = client.get_enc_keys(
+            slave_sae_id, number=number, size=size, method=method.upper()
+        )
+    except KMEError as e:
+        err_console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+    if as_json:
+        print(json.dumps(
+            [{"key_id": k.key_id, "key_hex": k.key.hex(), "size_bits": k.size_bits}
+             for k in keys],
+            indent=2,
+        ))
+    else:
+        for k in keys:
+            console.print(f"  [cyan]{k.key_id}[/]  {k.key.hex()}  ({k.size_bits}b)")
+
+
+@keys_app.command("retrieve", help="Slave SAE: retrieve keys by key_ID via dec_keys.")
+def keys_retrieve(
+    base_url: str = typer.Argument(...),
+    slave_sae_id: str = typer.Argument(...),
+    key_ids: list[str] = typer.Argument(..., help="One or more key_IDs."),
+    cert: Optional[Path] = typer.Option(None, "--cert"),
+    key: Optional[Path] = typer.Option(None, "--key"),
+    ca_cert: Optional[Path] = typer.Option(None, "--ca-cert"),
+    insecure: bool = typer.Option(False, "--insecure"),
+    timeout: float = typer.Option(30.0, "--timeout"),
+    as_json: bool = typer.Option(False, "--json"),
+) -> None:
+    client = _build_client(base_url, cert, key, ca_cert, insecure, timeout)
+    try:
+        keys = client.get_dec_keys(slave_sae_id, key_ids=key_ids)
+    except KMEError as e:
+        err_console.print(f"[red]Error:[/] {e}")
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+    if as_json:
+        print(json.dumps(
+            [{"key_id": k.key_id, "key_hex": k.key.hex(), "size_bits": k.size_bits}
+             for k in keys],
+            indent=2,
+        ))
+    else:
+        for k in keys:
+            console.print(f"  [cyan]{k.key_id}[/]  {k.key.hex()}  ({k.size_bits}b)")
+
+
+# ── version ───────────────────────────────────────────────────────────────
+
+
+@app.command(help="Print the qkdsec version.")
+def version() -> None:
+    print(__version__)
+
+
+if __name__ == "__main__":
+    app()

qkdsec/client/__init__.py

@@ -0,0 +1,35 @@
+"""ETSI GS QKD 014 REST client for Key Management Entity (KME) systems.
+
+Use this to fetch quantum keys from real QKD hardware (Toshiba, ID Quantique,
+QuantumCTek, etc.) or from a local KME simulator. Both synchronous and
+asynchronous clients are provided.
+
+Sync example:
+    >>> from qkdsec.client import ETSI014Client
+    >>> kme = ETSI014Client("https://kme.example.com",
+    ...                     client_cert=("alice.crt", "alice.key"))
+    >>> status = kme.status("sae-bob")
+    >>> keys = kme.get_enc_keys("sae-bob", number=1, size=256)
+
+Async example (requires ``pip install qkdsec[async]``)::
+
+    from qkdsec.client.aio import AsyncETSI014Client
+
+    async with AsyncETSI014Client("https://kme.example.com",
+                                  client_cert=("alice.crt", "alice.key")) as kme:
+        keys = await kme.get_enc_keys("sae-bob", number=1, size=256)
+"""
+
+from ._types import KeyResponse, KeysContainer, StatusResponse
+from .errors import KMEError, KMEHTTPError, KMENotFoundError
+from .etsi014 import ETSI014Client
+
+__all__ = [
+    "ETSI014Client",
+    "KeyResponse",
+    "KeysContainer",
+    "StatusResponse",
+    "KMEError",
+    "KMEHTTPError",
+    "KMENotFoundError",
+]

qkdsec/client/_types.py

@@ -0,0 +1,86 @@
+"""Response types for the ETSI GS QKD 014 client.
+
+The types here cover the full ETSI GS QKD 014 v1.1.1 spec, including vendor
+extensions. All extension fields are optional; the client populates them when
+present in the KME response and leaves them as ``None`` otherwise.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass(frozen=True)
+class KeyResponse:
+    """A single key fetched from the KME (ETSI 014 §5.3.3 / §5.4.3).
+
+    Attributes
+    ----------
+    key_id : str
+        The KME-assigned key identifier (UUID). Used to retrieve the matching
+        key on the slave SAE via ``get_dec_keys``.
+    key : bytes
+        The raw key material. The wire format is base64; this field is
+        already decoded.
+    key_id_extension : dict, optional
+        Vendor-specific or non-standard extension data attached to the key
+        identifier (ETSI 014 §5.3.3 ``key_ID_extension``).
+    key_extension : dict, optional
+        Vendor-specific or non-standard extension data attached to the key
+        itself (ETSI 014 §5.3.3 ``key_extension``).
+    """
+
+    key_id: str
+    key: bytes
+    key_id_extension: Optional[dict[str, Any]] = None
+    key_extension: Optional[dict[str, Any]] = None
+
+    @property
+    def size_bits(self) -> int:
+        return len(self.key) * 8
+
+
+@dataclass(frozen=True)
+class KeysContainer:
+    """A container of keys returned by enc_keys / dec_keys (ETSI 014 §5.3.3).
+
+    Wraps ``list[KeyResponse]`` to also surface the optional container-level
+    extension. Iterating over a ``KeysContainer`` yields its keys, so most
+    callers can treat it like a list.
+
+    Attributes
+    ----------
+    keys : list[KeyResponse]
+    key_container_extension : dict, optional
+        Vendor-specific extension data attached to the container as a whole
+        (ETSI 014 §5.3.3 ``key_container_extension``).
+    """
+
+    keys: list[KeyResponse] = field(default_factory=list)
+    key_container_extension: Optional[dict[str, Any]] = None
+
+    def __iter__(self):
+        return iter(self.keys)
+
+    def __len__(self) -> int:
+        return len(self.keys)
+
+    def __getitem__(self, idx: int) -> KeyResponse:
+        return self.keys[idx]
+
+
+@dataclass(frozen=True)
+class StatusResponse:
+    """KME status for a given slave SAE (ETSI GS QKD 014 §5.2)."""
+
+    source_kme_id: str
+    target_kme_id: str
+    master_sae_id: str
+    slave_sae_id: str
+    key_size: int
+    stored_key_count: int
+    max_key_count: int
+    max_key_per_request: int
+    max_key_size: int
+    min_key_size: int
+    max_sae_id_count: int
+    status_extension: Optional[dict[str, Any]] = None

qkdsec/client/aio.py

@@ -0,0 +1,236 @@
+"""Asynchronous ETSI GS QKD 014 client (httpx-based).
+
+Requires the ``async`` extra: ``pip install qkdsec[async]``.
+
+The async client mirrors the sync ``ETSI014Client`` API one-for-one. Parsers
+are shared with the sync client to keep response handling consistent.
+
+Example::
+
+    from qkdsec.client.aio import AsyncETSI014Client
+
+    async with AsyncETSI014Client(
+        "https://kme.example.com",
+        client_cert=("alice.crt", "alice.key"),
+    ) as kme:
+        status = await kme.status("sae-bob")
+        keys = await kme.get_enc_keys("sae-bob", number=1, size=256)
+"""
+
+from typing import Any, Optional, Union
+
+try:
+    import httpx
+except ImportError as e:
+    raise ImportError(
+        "qkdsec.client.aio requires extra dependencies. "
+        "Install with: pip install qkdsec[async]"
+    ) from e
+
+from ._types import KeyResponse, KeysContainer, StatusResponse
+from .errors import KMEHTTPError, KMENotFoundError
+from .etsi014 import ETSI014Client
+
+_API_PREFIX = "/api/v1/keys"
+
+
+CertType = Union[str, tuple[str, str], None]
+VerifyType = Union[bool, str]
+
+
+class AsyncETSI014Client:
+    """Asynchronous client for an ETSI GS QKD 014 KME.
+
+    Parameters mirror :class:`qkdsec.client.ETSI014Client` exactly.
+
+    Use as an async context manager to ensure the underlying httpx client
+    is closed::
+
+        async with AsyncETSI014Client(...) as kme:
+            await kme.status("sae-bob")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        client_cert: CertType = None,
+        verify: VerifyType = True,
+        timeout: float = 30.0,
+        extra_headers: Optional[dict] = None,
+        client: Optional[httpx.AsyncClient] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.client_cert = client_cert
+        self.verify = verify
+        self.timeout = timeout
+        self.extra_headers = dict(extra_headers or {})
+
+        if client is None:
+            self._client = httpx.AsyncClient(
+                cert=client_cert,
+                verify=verify,
+                timeout=timeout,
+                headers=self.extra_headers,
+            )
+            self._owns_client = True
+        else:
+            self._client = client
+            self._owns_client = False
+
+    # ── Status ─────────────────────────────────────────────────────────────
+
+    async def status(self, slave_sae_id: str) -> StatusResponse:
+        """Fetch KME status for the given slave SAE (ETSI 014 §5.2)."""
+        url = f"{self.base_url}{_API_PREFIX}/{slave_sae_id}/status"
+        data = await self._get_json(url)
+        return ETSI014Client._parse_status(data)
+
+    # ── enc_keys (master SAE) ──────────────────────────────────────────────
+
+    async def get_enc_keys(
+        self,
+        slave_sae_id: str,
+        *,
+        number: int = 1,
+        size: int = 256,
+        method: str = "GET",
+        additional_slave_sae_ids: Optional[list[str]] = None,
+        extension_mandatory: Optional[list[dict[str, Any]]] = None,
+        extension_optional: Optional[list[dict[str, Any]]] = None,
+    ) -> list[KeyResponse]:
+        """Fetch encryption keys for the master SAE (ETSI 014 §5.3)."""
+        container = await self.get_enc_keys_container(
+            slave_sae_id,
+            number=number,
+            size=size,
+            method=method,
+            additional_slave_sae_ids=additional_slave_sae_ids,
+            extension_mandatory=extension_mandatory,
+            extension_optional=extension_optional,
+        )
+        return container.keys
+
+    async def get_enc_keys_container(
+        self,
+        slave_sae_id: str,
+        *,
+        number: int = 1,
+        size: int = 256,
+        method: str = "GET",
+        additional_slave_sae_ids: Optional[list[str]] = None,
+        extension_mandatory: Optional[list[dict[str, Any]]] = None,
+        extension_optional: Optional[list[dict[str, Any]]] = None,
+    ) -> KeysContainer:
+        """Fetch encryption keys and return the full ETSI 014 §5.3 container."""
+        force_post = bool(
+            additional_slave_sae_ids
+            or extension_mandatory
+            or extension_optional
+        )
+        actual_method = "POST" if force_post else method.upper()
+
+        url = f"{self.base_url}{_API_PREFIX}/{slave_sae_id}/enc_keys"
+        if actual_method == "GET":
+            data = await self._get_json(
+                url, params={"number": number, "size": size}
+            )
+        elif actual_method == "POST":
+            body: dict[str, Any] = {"number": number, "size": size}
+            if additional_slave_sae_ids:
+                body["additional_slave_SAE_IDs"] = list(additional_slave_sae_ids)
+            if extension_mandatory:
+                body["extension_mandatory"] = list(extension_mandatory)
+            if extension_optional:
+                body["extension_optional"] = list(extension_optional)
+            data = await self._post_json(url, json=body)
+        else:
+            raise ValueError(
+                f"method must be 'GET' or 'POST', got {method!r}"
+            )
+        return ETSI014Client._parse_keys_container(data)
+
+    # ── dec_keys (slave SAE) ───────────────────────────────────────────────
+
+    async def get_dec_keys(
+        self,
+        slave_sae_id: str,
+        *,
+        key_ids: list[str],
+        key_id_extensions: Optional[dict[str, dict[str, Any]]] = None,
+        key_ids_extension: Optional[dict[str, Any]] = None,
+    ) -> list[KeyResponse]:
+        """Fetch specific keys by key_ID for the slave SAE (ETSI 014 §5.4)."""
+        container = await self.get_dec_keys_container(
+            slave_sae_id,
+            key_ids=key_ids,
+            key_id_extensions=key_id_extensions,
+            key_ids_extension=key_ids_extension,
+        )
+        return container.keys
+
+    async def get_dec_keys_container(
+        self,
+        slave_sae_id: str,
+        *,
+        key_ids: list[str],
+        key_id_extensions: Optional[dict[str, dict[str, Any]]] = None,
+        key_ids_extension: Optional[dict[str, Any]] = None,
+    ) -> KeysContainer:
+        """Fetch keys by key_ID and return the full ETSI 014 §5.4 container."""
+        if not key_ids:
+            raise ValueError("key_ids must be a non-empty list")
+        url = f"{self.base_url}{_API_PREFIX}/{slave_sae_id}/dec_keys"
+        ext_map = key_id_extensions or {}
+        items: list[dict[str, Any]] = []
+        for kid in key_ids:
+            entry: dict[str, Any] = {"key_ID": kid}
+            if kid in ext_map:
+                entry["key_ID_extension"] = ext_map[kid]
+            items.append(entry)
+        body: dict[str, Any] = {"key_IDs": items}
+        if key_ids_extension:
+            body["key_IDs_extension"] = key_ids_extension
+        data = await self._post_json(url, json=body)
+        return ETSI014Client._parse_keys_container(data)
+
+    # ── Lifecycle ──────────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client (if owned by this instance)."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncETSI014Client":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.aclose()
+
+    # ── HTTP helpers ───────────────────────────────────────────────────────
+
+    async def _get_json(self, url: str, params: Optional[dict] = None) -> dict:
+        response = await self._client.get(url, params=params)
+        return self._handle_response(response)
+
+    async def _post_json(self, url: str, json: dict) -> dict:
+        response = await self._client.post(
+            url,
+            json=json,
+            headers={"Content-Type": "application/json"},
+        )
+        return self._handle_response(response)
+
+    @staticmethod
+    def _handle_response(response: "httpx.Response") -> dict:
+        if response.is_success:
+            return response.json()
+
+        try:
+            message = response.json().get("message", response.text)
+        except ValueError:
+            message = response.text
+
+        if response.status_code == 404:
+            raise KMENotFoundError(message)
+        raise KMEHTTPError(response.status_code, message)

qkdsec/client/errors.py

@@ -0,0 +1,28 @@
+"""Exception types raised by the ETSI 014 client."""
+
+
+class KMEError(Exception):
+    """Base class for all KME client errors."""
+
+
+class KMEHTTPError(KMEError):
+    """Raised when the KME returns a non-2xx HTTP response.
+
+    Attributes
+    ----------
+    status_code : int
+    message : str
+        The KME's error message (or response body), if available.
+    """
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(f"KME returned HTTP {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+class KMENotFoundError(KMEHTTPError):
+    """Raised on HTTP 404 (e.g., key_ID not found or already retrieved)."""
+
+    def __init__(self, message: str):
+        super().__init__(404, message)