Metadata-Version: 2.4
Name: qkdsec
Version: 0.2.0
Summary: A developer toolkit for Quantum Key Distribution: numerical security proofs, BB84 simulation, and a full ETSI GS QKD 014 client with built-in conformance probe
Author-email: John Jepsen <jjepsen15@protonmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/John-Jepsen/qkdsec
Project-URL: Repository, https://github.com/John-Jepsen/qkdsec
Project-URL: Issues, https://github.com/John-Jepsen/qkdsec/issues
Keywords: qkd,quantum,cryptography,bb84,etsi,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: proofs
Requires-Dist: cvxpy>=1.5; extra == "proofs"
Requires-Dist: numpy>=1.24; extra == "proofs"
Requires-Dist: scipy>=1.10; extra == "proofs"
Provides-Extra: proofs-mosek
Requires-Dist: mosek>=10; extra == "proofs-mosek"
Provides-Extra: proofs-diff
Requires-Dist: cvxpylayers>=0.1.6; extra == "proofs-diff"
Requires-Dist: torch>=2; extra == "proofs-diff"
Provides-Extra: sim
Requires-Dist: qiskit>=2.0; extra == "sim"
Requires-Dist: qiskit-aer>=0.17; extra == "sim"
Provides-Extra: async
Requires-Dist: httpx>=0.27; extra == "async"
Provides-Extra: cli
Requires-Dist: typer>=0.12; extra == "cli"
Requires-Dist: rich>=13; extra == "cli"
Provides-Extra: doctor
Requires-Dist: httpx>=0.27; extra == "doctor"
Requires-Dist: typer>=0.12; extra == "doctor"
Requires-Dist: rich>=13; extra == "doctor"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo>=2024.5; extra == "docs"
Requires-Dist: myst-parser>=3; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Provides-Extra: all
Requires-Dist: cvxpy>=1.5; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: scipy>=1.10; extra == "all"
Requires-Dist: qiskit>=2.0; extra == "all"
Requires-Dist: qiskit-aer>=0.17; extra == "all"
Requires-Dist: httpx>=0.27; extra == "all"
Requires-Dist: typer>=0.12; extra == "all"
Requires-Dist: rich>=13; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: responses>=0.24; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# qkdsec

[![PyPI](https://img.shields.io/pypi/v/qkdsec.svg)](https://pypi.org/project/qkdsec/)
[![Python](https://img.shields.io/pypi/pyversions/qkdsec.svg)](https://pypi.org/project/qkdsec/)
[![CI](https://github.com/John-Jepsen/qkdsec/actions/workflows/ci.yml/badge.svg)](https://github.com/John-Jepsen/qkdsec/actions/workflows/ci.yml)
[![Docs](https://readthedocs.org/projects/qkdsec/badge/?version=latest)](https://qkdsec.readthedocs.io/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

A developer toolkit for Quantum Key Distribution: numerical security proofs, BB84 simulation, and an ETSI GS QKD 014 client with a built-in KME conformance probe.

`qkdsec` is one library with three subpackages, each addressing a different need:

- **`qkdsec.proofs`** — Provable secret-key-rate lower bounds for QKD protocols under given channel models.
- **`qkdsec.sim`** — Working BB84 simulator (Qiskit and classical backends).
- **`qkdsec.client`** — Full ETSI GS QKD 014 v1.1.1 client (sync **and** async), plus a `qkdsec doctor` conformance probe that audits any KME.

## What sets it apart

- **`qkdsec doctor`** — point it at any KME and get a colored conformance report against ETSI GS QKD 014 v1.1.1. Catches spec violations before they bite production. JSON output for CI; HTML output for sharing.
- **Full spec coverage** — multicast key delivery (`additional_slave_SAE_IDs`), mandatory/optional vendor extensions, and container-level metadata. Most KME clients only implement the happy path.
- **Sync and async** — `ETSI014Client` for scripts and `AsyncETSI014Client` for FastAPI / asyncio services. Same surface, share parsers.
- **Lightweight default** — `pip install qkdsec` brings only `requests`. Heavy deps (CVXPY, Qiskit, httpx, typer) are behind extras.

## Install

```bash
# ETSI 014 client only (sync, lightweight)
pip install qkdsec

# + async client
pip install "qkdsec[async]"

# + qkdsec CLI and doctor (recommended for ops)
pip install "qkdsec[doctor]"

# + numerical security proofs
pip install "qkdsec[proofs]"

# + BB84 simulator (Qiskit backend)
pip install "qkdsec[sim]"

# Everything
pip install "qkdsec[all]"
```

## Quick start

### Audit a KME in 30 seconds

```bash
qkdsec doctor https://kme.example.com \
    --slave-sae-id sae-bob \
    --cert alice.crt --key alice.key
```

```
qkdsec doctor — https://kme.example.com
slave SAE: sae-bob

  PASS  reachability         [§5.2]      45 ms
  PASS  status_fields        [§5.2.2]    12 ms
  PASS  enc_keys_get         [§5.3]     108 ms
  PASS  enc_keys_post        [§5.3]      94 ms
  PASS  enc_keys_caps        [§5.3]      31 ms
  WARN  extensions_accepted  [§5.3.2]    28 ms
        KME returned HTTP 400 with extension_optional present.
  PASS  dec_keys_roundtrip   [§5.4]     142 ms
  PASS  error_contract_404   [§5.4]      19 ms
  PASS  error_contract_400   [§5.3]      18 ms
  PASS  latency                          14 ms

  Summary: 9 pass, 1 warn, 0 fail, 0 skip
  Verdict: CONFORMANT  (511 ms total)
```

Exit code 0 if conformant, 1 if not — drop in CI directly.

### Fetch a key (sync)

```python
from qkdsec.client import ETSI014Client

with ETSI014Client(
    "https://kme.example.com",
    client_cert=("alice.crt", "alice.key"),
) as kme:
    keys = kme.get_enc_keys("sae-bob", number=1, size=256)
    print(keys[0].key.hex())
```

### Fetch a key (async)

```python
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)
```

### Compute a provable key rate

```python
from qkdsec.proofs import key_rate, BB84, DepolarizingChannel

result = key_rate(BB84(), DepolarizingChannel(qber=0.03))
print(f"Lower bound: {result.r_lower:.4f} bits/pulse")
```

### Simulate a BB84 exchange

```python
from qkdsec.sim import BB84Protocol

result = BB84Protocol(error_rate=0.01).run(n_bits=4096)
if result.secure:
    print(result.final_key.hex())
```

## Standards

- **ETSI GS QKD 014 v1.1.1** — REST API for key delivery (full coverage)
- **BB84** (Bennett & Brassard, 1984)
- **Shor–Preskill** asymptotic key rate
- **Tomamichel et al.** finite-key correction
- **Two-decoy state** estimation

## Documentation

Full docs at [qkdsec.readthedocs.io](https://qkdsec.readthedocs.io/) — quickstart, doctor guide, async guide, spec coverage walk-through, and API reference.

## Scope and non-goals

- **What this is:** a developer-facing library for the three roles above.
- **What this is not:** a complete QKD network, a hybrid QKD+PQC system, or a vendor-specific SDK. QKD itself requires quantum hardware (single-photon sources and detectors over an optical channel). This library helps you build *around* that hardware.

## License

Apache-2.0
