rfc9180-py

A Python implementation of Hybrid Public Key Encryption (HPKE) as specified in RFC 9180.

Overview

HPKE provides a variant of public key encryption for arbitrary-sized plaintexts. It combines:

• A Key Encapsulation Mechanism (KEM) — asymmetric

• A Key Derivation Function (KDF) — for key schedule and exports

• An Authenticated Encryption with Associated Data (AEAD) algorithm

This library implements the core HPKE specification using Python’s cryptography library, with both single-shot and multi-shot (context) APIs for all HPKE modes.

Features

• All HPKE modes: Base, PSK, Auth, and AuthPSK

• Multiple ciphersuites: KEM (X25519, X448, P-256, P-384, P-521), KDF (HKDF-SHA256/384/512), AEAD (AES-128/256-GCM, ChaCha20-Poly1305, EXPORT_ONLY)

• Single-shot APIs: One-call seal/open per mode

• Context APIs: Multi-message encryption with automatic nonce management

• Secret export: Export application secrets from HPKE contexts (single-shot and context APIs)

• Key management: Generate, derive, serialize keys; accept keys as bytes, key objects, or JWK/PEM

• JWK and PEM support: Load keys from JSON Web Key (EC, X25519, X448) or PEM format via KEMKey

• Message encoding helpers: Self-describing header format (append_header / parse_header)

Contents

• Installation
  • Requirements
  • Install from PyPI
  • Install from source
  • Development and documentation
  • How the docs work
• Quick Start
  • Create an HPKE instance
  • Key generation and serialization
  • Single-shot encryption (Base mode)
  • Other single-shot modes
  • Multi-shot (context) API
  • Secret export
  • Message encoding helpers
  • Using different ciphersuites
  • Using keys from JWK or PEM
  • Error handling
• Examples
  • Complete Base Mode Example
  • Auth Mode with Sender Authentication
  • PSK Mode with Pre-Shared Key
  • Multi-Message Context (Streaming)
  • Export-Only (Key Agreement)
  • Keys from JWK
  • Self-Describing Wire Format
  • Different Ciphersuites
• API Reference
  • Public API

Indices and tables

• Index

• Module Index

• Search Page