hpke-http 0.1.2__py3-none-any.whl

hpke_http/__init__.py

@@ -0,0 +1,52 @@
+"""
+RFC 9180 HPKE encryption library for HTTP transport.
+
+This library provides transparent end-to-end encryption for SDK ↔ Platform communication
+using RFC 9180 HPKE (Hybrid Public Key Encryption) with PSK mode.
+
+Usage (Server - FastAPI):
+    from hpke_http.middleware.fastapi import HPKEMiddleware
+
+    app = FastAPI()
+    app.add_middleware(HPKEMiddleware, private_key=settings.hpke_private_key)
+
+Usage (Client - aiohttp):
+    from hpke_http.middleware.aiohttp import HPKEClientSession
+
+    async with HPKEClientSession(base_url="https://api.example.com", psk=api_key) as session:
+        async with session.post("/tasks", json=data) as response:
+            async for event in session.iter_sse(response):
+                print(event)
+"""
+
+from importlib.metadata import version
+
+from hpke_http.constants import AEAD_ID, KDF_ID, KEM_ID, MODE_PSK, VERSION
+from hpke_http.exceptions import (
+    CryptoError,
+    DecryptionError,
+    EnvelopeError,
+    InvalidPSKError,
+    UnsupportedSuiteError,
+)
+
+__all__ = [
+    # Constants
+    "AEAD_ID",
+    "KDF_ID",
+    "KEM_ID",
+    "MODE_PSK",
+    "VERSION",
+    # Exceptions
+    "CryptoError",
+    "DecryptionError",
+    "EnvelopeError",
+    "InvalidPSKError",
+    "UnsupportedSuiteError",
+    # Versioning
+    "__version__",
+    "__version_full__",
+]
+
+__version__ = version("hpke_http")
+__version_full__ = "0.1.2-8c80fcb+HEAD.20260107115221"

hpke_http/constants.py

@@ -0,0 +1,232 @@
+"""
+RFC 9180 HPKE constants and algorithm identifiers.
+
+Cipher Suite:
+- KEM: DHKEM(X25519, HKDF-SHA256) - 0x0020
+- KDF: HKDF-SHA256 - 0x0001
+- AEAD: ChaCha20-Poly1305 - 0x0003
+- Mode: PSK - 0x01
+
+References:
+- RFC 9180 §7.1 (KEM IDs)
+- RFC 9180 §7.2 (KDF IDs)
+- RFC 9180 §7.3 (AEAD IDs)
+- RFC 9180 §5.1.2 (PSK mode)
+"""
+
+from enum import IntEnum
+from typing import Final
+
+# =============================================================================
+# HPKE Version
+# =============================================================================
+
+VERSION: Final[bytes] = b"HPKE-v1"
+"""HPKE version string used in labeled operations (RFC 9180 §4)."""
+
+# =============================================================================
+# KEM Identifiers (RFC 9180 §7.1)
+# =============================================================================
+
+
+class KemId(IntEnum):
+    """Key Encapsulation Mechanism identifiers."""
+
+    DHKEM_X25519_HKDF_SHA256 = 0x0020
+    """DHKEM(X25519, HKDF-SHA256) - RFC 9180 recommended."""
+
+    # Future: X-Wing (X25519 + ML-KEM-768) - draft-connolly-cfrg-xwing-kem
+    # X_WING = 0x647A
+
+
+# Default KEM for this implementation
+KEM_ID: Final[int] = KemId.DHKEM_X25519_HKDF_SHA256
+
+# X25519 key sizes
+X25519_PUBLIC_KEY_SIZE: Final[int] = 32
+X25519_PRIVATE_KEY_SIZE: Final[int] = 32
+X25519_SHARED_SECRET_SIZE: Final[int] = 32
+X25519_ENC_SIZE: Final[int] = 32  # Encapsulated key size
+
+# =============================================================================
+# KDF Identifiers (RFC 9180 §7.2)
+# =============================================================================
+
+
+class KdfId(IntEnum):
+    """Key Derivation Function identifiers."""
+
+    HKDF_SHA256 = 0x0001
+    """HKDF-SHA256 - RFC 5869."""
+
+
+# Default KDF for this implementation
+KDF_ID: Final[int] = KdfId.HKDF_SHA256
+
+# HKDF-SHA256 parameters
+HKDF_SHA256_HASH_SIZE: Final[int] = 32
+HKDF_SHA256_N_SECRET: Final[int] = 32  # Output size of Extract
+HKDF_SHA256_N_H: Final[int] = 32  # Hash output size
+
+# =============================================================================
+# AEAD Identifiers (RFC 9180 §7.3)
+# =============================================================================
+
+
+class AeadId(IntEnum):
+    """Authenticated Encryption with Associated Data identifiers."""
+
+    AES_128_GCM = 0x0001
+    AES_256_GCM = 0x0002
+    CHACHA20_POLY1305 = 0x0003
+    """ChaCha20-Poly1305 - RFC 8439."""
+
+
+# Default AEAD for this implementation
+AEAD_ID: Final[int] = AeadId.CHACHA20_POLY1305
+
+# ChaCha20-Poly1305 parameters (RFC 8439)
+CHACHA20_POLY1305_KEY_SIZE: Final[int] = 32
+CHACHA20_POLY1305_NONCE_SIZE: Final[int] = 12
+CHACHA20_POLY1305_TAG_SIZE: Final[int] = 16
+
+# =============================================================================
+# HPKE Mode Identifiers (RFC 9180 §5)
+# =============================================================================
+
+
+class HpkeMode(IntEnum):
+    """HPKE operation modes."""
+
+    BASE = 0x00
+    """Base mode - no additional keying material."""
+    PSK = 0x01
+    """PSK mode - Pre-Shared Key for additional authentication."""
+    AUTH = 0x02
+    """Auth mode - Sender authentication via static key."""
+    AUTH_PSK = 0x03
+    """AuthPSK mode - Both sender auth and PSK."""
+
+
+# Default mode for this implementation
+MODE_PSK: Final[int] = HpkeMode.PSK
+
+# PSK minimum size for cryptographic security (256 bits)
+PSK_MIN_SIZE: Final[int] = 32
+
+# =============================================================================
+# Suite ID Construction (RFC 9180 §5.1)
+# =============================================================================
+
+
+def build_suite_id(kem_id: int = KEM_ID, kdf_id: int = KDF_ID, aead_id: int = AEAD_ID) -> bytes:
+    """
+    Build the suite_id for HPKE operations.
+
+    suite_id = "HPKE" || I2OSP(kem_id, 2) || I2OSP(kdf_id, 2) || I2OSP(aead_id, 2)
+
+    Args:
+        kem_id: KEM algorithm identifier
+        kdf_id: KDF algorithm identifier
+        aead_id: AEAD algorithm identifier
+
+    Returns:
+        10-byte suite_id
+    """
+    return b"HPKE" + kem_id.to_bytes(2, "big") + kdf_id.to_bytes(2, "big") + aead_id.to_bytes(2, "big")
+
+
+# Default suite ID for DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305
+SUITE_ID: Final[bytes] = build_suite_id()
+
+# =============================================================================
+# Wire Format Constants
+# =============================================================================
+
+# Envelope header size: version(1) + kem_id(2) + kdf_id(2) + aead_id(2) + mode(1) = 8 bytes
+ENVELOPE_HEADER_SIZE: Final[int] = 8
+
+# Current envelope version
+ENVELOPE_VERSION: Final[int] = 0x01
+
+# =============================================================================
+# HTTP Header Names
+# =============================================================================
+
+HEADER_HPKE_ENC: Final[str] = "X-HPKE-Enc"
+"""Header containing base64url-encoded encapsulated key."""
+
+HEADER_HPKE_STREAM: Final[str] = "X-HPKE-Stream"
+"""Header containing encrypted SSE session parameters."""
+
+HEADER_HPKE_ENCODING: Final[str] = "X-HPKE-Encoding"
+"""Header specifying compression algorithm for request body (RFC 8878)."""
+
+# =============================================================================
+# ASGI Scope Keys
+# =============================================================================
+
+SCOPE_HPKE_CONTEXT: Final[str] = "hpke_context"
+"""ASGI scope key for storing HPKE recipient context after request decryption."""
+
+# =============================================================================
+# SSE Streaming Constants
+# =============================================================================
+
+SSE_SESSION_SALT_SIZE: Final[int] = 4
+"""Random salt size for SSE session nonces (4 bytes)."""
+
+SSE_COUNTER_SIZE: Final[int] = 4
+"""Counter size in wire format (4 bytes, big-endian)."""
+
+SSE_MAX_COUNTER: Final[int] = 2**32 - 1
+"""Maximum counter value (4 billion events per session)."""
+
+SSE_MAX_EVENT_SIZE: Final[int] = 64 * 1024 * 1024
+"""Default maximum buffered SSE event size (64MB).
+
+This is a DoS protection limit for incomplete events without proper \\n\\n boundaries.
+Can be overridden via HPKEMiddleware's max_sse_event_size parameter.
+
+Note: SSE is text-only (UTF-8). Binary data (images, documents) must be
+base64-encoded, which adds ~33% overhead. A 48MB file becomes ~64MB in base64.
+"""
+
+# Export label for deriving SSE session key from HPKE context
+SSE_SESSION_KEY_LABEL: Final[bytes] = b"sse-session-key"
+
+# =============================================================================
+# Key Discovery
+# =============================================================================
+
+DISCOVERY_PATH: Final[str] = "/.well-known/hpke-keys"
+"""Path for HPKE key discovery endpoint."""
+
+DISCOVERY_CACHE_MAX_AGE: Final[int] = 86400
+"""Default cache max-age for discovery response (24 hours)."""
+
+# =============================================================================
+# Compression Constants (RFC 8878 - Zstandard)
+# =============================================================================
+
+
+class SSEEncodingId(IntEnum):
+    """Encoding algorithm identifiers for SSE payloads.
+
+    First byte of decrypted SSE payload indicates compression algorithm.
+    Extensible for future algorithms (brotli, etc.).
+    """
+
+    IDENTITY = 0x00
+    """No compression - raw plaintext."""
+    ZSTD = 0x01
+    """Zstandard compression (RFC 8878)."""
+    # Reserved for future:
+    # BROTLI = 0x02  # Brotli (RFC 7932)
+
+
+ZSTD_COMPRESSION_LEVEL: Final[int] = 3
+"""Zstd compression level (1-22). Level 3 = fast compression."""
+
+ZSTD_MIN_SIZE: Final[int] = 64
+"""Minimum payload size for compression. Smaller payloads skip compression."""

hpke_http/envelope.py

@@ -0,0 +1,167 @@
+"""
+Wire format for HPKE encrypted envelopes.
+
+Envelope format (sent in HTTP body):
+┌─────────┬─────────┬─────────┬─────────┬──────┬────────────┐
+│Version  │ KEM_ID  │ KDF_ID  │ AEAD_ID │ Mode │ Ciphertext │
+│ (1B)    │  (2B)   │  (2B)   │  (2B)   │ (1B) │  (N+16B)   │
+└─────────┴─────────┴─────────┴─────────┴──────┴────────────┘
+
+The encapsulated key (enc) is sent in the X-HPKE-Enc HTTP header.
+
+Reference: RFC-065 §4.1
+"""
+
+from dataclasses import dataclass
+
+from hpke_http.constants import (
+    AEAD_ID,
+    CHACHA20_POLY1305_TAG_SIZE,
+    ENVELOPE_HEADER_SIZE,
+    ENVELOPE_VERSION,
+    KDF_ID,
+    KEM_ID,
+    MODE_PSK,
+)
+from hpke_http.exceptions import EnvelopeError, UnsupportedSuiteError
+
+__all__ = [
+    "EnvelopeHeader",
+    "decode_envelope",
+    "encode_envelope",
+    "parse_header",
+]
+
+
+@dataclass
+class EnvelopeHeader:
+    """Parsed envelope header."""
+
+    version: int
+    kem_id: int
+    kdf_id: int
+    aead_id: int
+    mode: int
+
+    def validate(self) -> None:
+        """
+        Validate that header uses supported cipher suite.
+
+        Raises:
+            EnvelopeError: If version is unsupported
+            UnsupportedSuiteError: If cipher suite is not supported
+        """
+        if self.version != ENVELOPE_VERSION:
+            raise EnvelopeError(f"Unsupported envelope version: {self.version}")
+
+        if self.kem_id != KEM_ID or self.kdf_id != KDF_ID or self.aead_id != AEAD_ID:
+            raise UnsupportedSuiteError(self.kem_id, self.kdf_id, self.aead_id)
+
+        if self.mode != MODE_PSK:
+            raise EnvelopeError(f"Unsupported HPKE mode: {self.mode} (only PSK mode 0x01 supported)")
+
+
+def encode_header(
+    version: int = ENVELOPE_VERSION,
+    kem_id: int = KEM_ID,
+    kdf_id: int = KDF_ID,
+    aead_id: int = AEAD_ID,
+    mode: int = MODE_PSK,
+) -> bytes:
+    """
+    Encode envelope header.
+
+    Args:
+        version: Envelope format version
+        kem_id: KEM algorithm identifier
+        kdf_id: KDF algorithm identifier
+        aead_id: AEAD algorithm identifier
+        mode: HPKE mode
+
+    Returns:
+        8-byte header
+    """
+    return (
+        version.to_bytes(1, "big")
+        + kem_id.to_bytes(2, "big")
+        + kdf_id.to_bytes(2, "big")
+        + aead_id.to_bytes(2, "big")
+        + mode.to_bytes(1, "big")
+    )
+
+
+def parse_header(data: bytes) -> EnvelopeHeader:
+    """
+    Parse envelope header from bytes.
+
+    Args:
+        data: At least 8 bytes starting with header
+
+    Returns:
+        Parsed EnvelopeHeader
+
+    Raises:
+        EnvelopeError: If data is too short
+    """
+    if len(data) < ENVELOPE_HEADER_SIZE:
+        raise EnvelopeError(f"Envelope too short: {len(data)} bytes (minimum {ENVELOPE_HEADER_SIZE})")
+
+    return EnvelopeHeader(
+        version=data[0],
+        kem_id=int.from_bytes(data[1:3], "big"),
+        kdf_id=int.from_bytes(data[3:5], "big"),
+        aead_id=int.from_bytes(data[5:7], "big"),
+        mode=data[7],
+    )
+
+
+def encode_envelope(ciphertext: bytes) -> bytes:
+    """
+    Encode ciphertext into envelope format.
+
+    The encapsulated key (enc) should be sent separately in X-HPKE-Enc header.
+
+    Args:
+        ciphertext: AEAD-encrypted data with authentication tag
+
+    Returns:
+        Complete envelope: header || ciphertext
+    """
+    header = encode_header()
+    return header + ciphertext
+
+
+def decode_envelope(envelope: bytes) -> tuple[EnvelopeHeader, bytes]:
+    """
+    Decode envelope into header and ciphertext.
+
+    Args:
+        envelope: Complete envelope bytes
+
+    Returns:
+        Tuple of (header, ciphertext)
+
+    Raises:
+        EnvelopeError: If envelope is malformed
+        UnsupportedSuiteError: If cipher suite is not supported
+    """
+    if len(envelope) < ENVELOPE_HEADER_SIZE + CHACHA20_POLY1305_TAG_SIZE:
+        raise EnvelopeError(
+            f"Envelope too short: {len(envelope)} bytes (minimum {ENVELOPE_HEADER_SIZE + CHACHA20_POLY1305_TAG_SIZE})"
+        )
+
+    header = parse_header(envelope)
+    header.validate()
+
+    ciphertext = envelope[ENVELOPE_HEADER_SIZE:]
+    return (header, ciphertext)
+
+
+def envelope_overhead() -> int:
+    """
+    Calculate total overhead added by envelope encoding.
+
+    Returns:
+        Overhead in bytes (header + AEAD tag)
+    """
+    return ENVELOPE_HEADER_SIZE + CHACHA20_POLY1305_TAG_SIZE

hpke_http/exceptions.py

@@ -0,0 +1,80 @@
+"""
+Exception hierarchy for hpke_http.
+
+All crypto-related errors inherit from CryptoError for easy catching.
+"""
+
+
+class CryptoError(Exception):
+    """Base exception for all cryptographic errors."""
+
+
+class DecryptionError(CryptoError):
+    """Failed to decrypt ciphertext.
+
+    Possible causes:
+    - Wrong key
+    - Corrupted ciphertext
+    - Invalid authentication tag
+    - Nonce reuse detected
+    """
+
+
+class InvalidPSKError(CryptoError):
+    """Pre-shared key validation failed.
+
+    The PSK (API key) doesn't match what was used for encryption.
+    """
+
+
+class UnsupportedSuiteError(CryptoError):
+    """Cipher suite not supported.
+
+    The envelope uses a KEM/KDF/AEAD combination this implementation doesn't support.
+    """
+
+    def __init__(self, kem_id: int, kdf_id: int, aead_id: int) -> None:
+        self.kem_id = kem_id
+        self.kdf_id = kdf_id
+        self.aead_id = aead_id
+        super().__init__(f"Unsupported suite: kem=0x{kem_id:04x}, kdf=0x{kdf_id:04x}, aead=0x{aead_id:04x}")
+
+
+class EnvelopeError(CryptoError):
+    """Invalid envelope format.
+
+    The encrypted envelope is malformed:
+    - Too short
+    - Invalid version
+    - Corrupted header
+    """
+
+
+class KeyDiscoveryError(CryptoError):
+    """Failed to fetch or parse HPKE keys from discovery endpoint."""
+
+
+class SequenceOverflowError(CryptoError):
+    """Sequence counter has reached maximum value.
+
+    The HPKE context can no longer be used for encryption/decryption.
+    Nonce reuse would be catastrophic for ChaCha20-Poly1305 security.
+    Create a new context to continue.
+    """
+
+
+class SessionExpiredError(CryptoError):
+    """SSE streaming session has expired or exhausted its counter."""
+
+
+class ReplayAttackError(CryptoError):
+    """Detected out-of-order or duplicate SSE event.
+
+    Counter validation failed, indicating potential replay attack.
+    """
+
+    def __init__(self, expected: int, received: int) -> None:
+        self.expected = expected
+        self.received = received
+        # Don't expose counter values in message to prevent information leakage
+        super().__init__("SSE event counter validation failed")

hpke_http/headers.py

@@ -0,0 +1,48 @@
+"""
+HTTP header utilities for HPKE encryption.
+
+Uses base64url encoding (RFC 4648 §5) for HTTP header safety.
+"""
+
+import base64
+
+from hpke_http.constants import HEADER_HPKE_ENC, HEADER_HPKE_STREAM
+
+__all__ = [
+    "HEADER_HPKE_ENC",
+    "HEADER_HPKE_STREAM",
+    "b64url_decode",
+    "b64url_encode",
+]
+
+
+def b64url_encode(data: bytes) -> str:
+    """
+    Encode bytes to base64url string without padding.
+
+    Args:
+        data: Raw bytes to encode
+
+    Returns:
+        base64url encoded string (no padding)
+    """
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(s: str) -> bytes:
+    """
+    Decode base64url string to bytes.
+
+    Handles missing padding automatically.
+
+    Args:
+        s: base64url encoded string (with or without padding)
+
+    Returns:
+        Decoded bytes
+    """
+    # Add padding if needed (base64 uses 4-byte blocks)
+    padding = len(s) % 4
+    if padding:
+        s += "=" * (4 - padding)
+    return base64.urlsafe_b64decode(s)