Add HPKE (Hybrid Public Key Encryption) support per RFC 9180 #14126

MkDev11 · 2026-01-09T13:33:16Z

Add HPKE (Hybrid Public Key Encryption) support per RFC 9180

Summary

This implements HPKE Base mode as defined in RFC 9180, providing a simple single-shot API for hybrid public key encryption.

What's Included

Single-shot API: suite.encrypt() and suite.decrypt() methods
KEM: X25519 (DHKEM)
KDF: HKDF-SHA256
AEAD: AES-128-GCM

API Design

from cryptography.hazmat.primitives.hpke import Suite, KEM, KDF, AEAD
from cryptography.hazmat.primitives.asymmetric import x25519

suite = Suite(KEM.X25519, KDF.HKDF_SHA256, AEAD.AES_128_GCM)

# Generate recipient keys
private_key = x25519.X25519PrivateKey.generate()
public_key = private_key.public_key()

# Encrypt (returns enc || ciphertext)
ciphertext = suite.encrypt(b"secret message", public_key, info=b"app", aad=b"data")

# Decrypt
plaintext = suite.decrypt(ciphertext, private_key, info=b"app", aad=b"data")

Design Decisions

Single-shot only: No multi-message context API in this initial version
enc || ct format: Like Go's single-shot HPKE API
Opaque enum values: Enum values are opaque strings, not RFC numeric identifiers

Closes

Closes #14073

alex · 2026-01-09T13:36:24Z

Please take a look at the failing CI jobs.

MkDev11 · 2026-01-09T16:29:31Z

@reaperhulk @alex can you please review the PR and let me know the result?

alex · 2026-01-09T16:33:41Z

Please be more patient. This PR will get reviewed, but we all have day jobs.

alex · 2026-01-10T03:34:13Z

A few high level notes, I haven't reviewed in depth yet:

Vectors should be submitted in a seperate PR, in the vectors/ director and documented in test-vectors.rst
We strongly avoid subclassing, it shouldn't be necessary here.
uv.lock shouldn't be checked in, not sure why that's here
The overall size of this PR is too large to be effectively reviewed. The best path is likely to pare this down to a single algorithm of each type and then we can add additional algorithms in follow up PRs.

alex

I started reviewing, however I think my request on trimming this down was unclear:

We still want the initial PR to have the overall structure and final API we want, we just want to trim it down by implementing it for only one of the algorithms to reduce the code to review.

src/cryptography/hazmat/primitives/hpke.py

alex

The API here still doesn't match what was discussed on the issue, so I think we may be talking past each other. Can you explain why this has a different API?

API changes per maintainer feedback: - Add Suite(KEM, KDF, AEAD) class with RFC parameter order - Add KEM, KDF, AEAD enum types for algorithm selection - suite.sender(public_key, info) returns SenderContext - suite.recipient(enc, private_key, info) returns RecipientContext - First encrypt() returns enc || ciphertext concatenated - Subsequent encrypt() calls return just ciphertext - Use encrypt/decrypt method names - Simpler KEM names (X25519 instead of DHKEM_X25519_HKDF_SHA256) This matches the API discussed in issue pyca#14073 and addresses reviewer feedback about the API mismatch.

alex

I see you're still working, so submitting some quick comments.

Are you intended to submit the vectors as a seperate PR?

src/cryptography/hazmat/primitives/hpke.py

- Replace TypedDict with frozen dataclasses for parameter types - Use HKDF.extract() static method instead of hmac.digest - Remove base HPKEError class, keep only MessageLimitReachedError - Use if/elif instead of match for Python 3.8 compatibility

MkDev11 · 2026-01-12T00:25:22Z

I see you're still working, so submitting some quick comments.

Are you intended to submit the vectors as a seperate PR?

yes, I plan to submit the test vectors as a separate PR. should I create that PR now, or wait until the API design is finalized based on your feedback about the enc prepending behavior and thread safety concerns?

alex · 2026-01-12T00:27:44Z

The vectors can be submitted concurrently if they're ready, thanks.

MkDev11 · 2026-01-12T00:34:43Z

The vectors can be submitted concurrently if they're ready, thanks.

sure, I can work on the vectors PR after this one is merged to avoid having multiple open PRs on Gittensor. is there any other feedback on the current implementation I should address in the meantime?

alex · 2026-01-12T00:36:40Z

I don't know what a git tensor is, but that's not going to dictate our development processes.

MkDev11 · 2026-01-12T00:38:17Z

I don't know what a git tensor is, but that's not going to dictate our development processes.

understood, apologies for the confusion. i'll prepare the vectors PR. in the meantime, are there any other changes needed on this PR? I'm still waiting on clarification about the enc prepending behavior (always vs first message only) and the thread safety concern you mentioned

The type system guarantees only valid enum values can be passed to these internal functions, so use assert which is excluded from coverage.

MkDev11 · 2026-01-12T23:56:40Z

thanks for merging my PR. could you please review the changes I made?

alex · 2026-01-13T00:05:40Z

It's on my TODO list. Unless we've been radio silent for several days, there's no need to follow up, we haven't forgotten.

src/cryptography/hazmat/primitives/hpke.py

tests/hazmat/primitives/test_hpke.py

…ctors - Remove first_message special behavior from SenderContext and RecipientContext - encrypt() now always returns just ciphertext, enc accessed via property - Remove try/except Exception - AESGCM.decrypt raises InvalidTag directly - Update tests to use new API (enc via sender.enc property) - Add test vector loading from RFC 9180 vectors (when available) - Update docstring example to show correct usage

MkDev11 · 2026-01-13T13:18:10Z

thanks for your feedback, just pushed the changes

alex · 2026-01-19T18:54:55Z

Hi, @reaperhulk and I discussed and we'd like to make the following changes to the API:

The enums for each KEM/AEAD/KDF shouldn't be the RFC value, they should just be opaque.
We want to start with a single-shot API only, so suite.encrypt() + suite.decrypt() with no multi-shot. The result will be enc || ct like Go's single-shot APIs.

This should hopefully make the PR much simpler/shorter to get started.

- Replace sender()/recipient() context methods with encrypt()/decrypt() - encrypt() returns enc || ciphertext (like Go's single-shot API) - decrypt() takes enc || ciphertext and returns plaintext - Make enum values opaque strings instead of RFC numeric values - Remove SenderContext, RecipientContext, MessageLimitReachedError - Update tests for new single-shot API

MkDev11 · 2026-01-19T21:00:49Z

Hi, @reaperhulk and I discussed and we'd like to make the following changes to the API:

The enums for each KEM/AEAD/KDF shouldn't be the RFC value, they should just be opaque.

We want to start with a single-shot API only, so suite.encrypt() + suite.decrypt() with no multi-shot. The result will be enc || ct like Go's single-shot APIs.

This should hopefully make the PR much simpler/shorter to get started.

Updated to single-shot API per feedback:

suite.encrypt() / suite.decrypt() instead of sender/recipient contexts
Returns enc || ciphertext like Go's API
Opaque enum values
Removed multi-message support for simplicity

src/cryptography/hazmat/primitives/hpke.py

tests/hazmat/primitives/test_hpke.py

- Remove docstrings (prose docs only) - Use load_vectors_from_file helper - Use [] instead of .get() for vector keys - Parameterize roundtrip tests by KEM/KDF/AEAD - Merge error test class into main test class - Use subtest fixture instead of parametrize for vectors - Remove test_load_vectors_missing_file test - Load vectors inside test function, not at module level

MkDev11 force-pushed the add-hpke-support branch 4 times, most recently from 770943f to c8d3bd2 Compare January 9, 2026 14:17

MkDev11 mentioned this pull request Jan 9, 2026

Add HPKE support #14073

Open

5 tasks

MkDev11 force-pushed the add-hpke-support branch 3 times, most recently from 035856c to d874aab Compare January 9, 2026 17:07

MkDev11 force-pushed the add-hpke-support branch 4 times, most recently from 0811f29 to 065b482 Compare January 10, 2026 12:38

alex reviewed Jan 10, 2026

View reviewed changes

Add HPKE support per RFC 9180

88b1024

MkDev11 force-pushed the add-hpke-support branch from 065b482 to 88b1024 Compare January 11, 2026 10:33

Trigger CI re-run

72d87fb

alex reviewed Jan 11, 2026

View reviewed changes

MkDev11 added 4 commits January 12, 2026 01:34

Fix ruff lint errors: unused import, line length, sorting

600fcf7

Fix ruff format

4875185

Fix mypy type errors with TypedDict for parameter dicts

cea619f

alex reviewed Jan 12, 2026

View reviewed changes

MkDev11 mentioned this pull request Jan 12, 2026

Add HPKE RFC 9180 test vectors #14132

Merged

Fix coverage: use assert instead of unreachable raise statements

75aefae

The type system guarantees only valid enum values can be passed to these internal functions, so use assert which is excluded from coverage.

alex reviewed Jan 13, 2026

View reviewed changes

Add test for load_vectors missing file branch

a60f52f

MkDev11 requested a review from alex January 19, 2026 01:31

MkDev11 added 2 commits January 19, 2026 22:46

Format test file with ruff

bdf4af7

Fix coverage: remove conditional branch in vector test

cd1c42a

alex reviewed Jan 19, 2026

View reviewed changes

Add HPKE (Hybrid Public Key Encryption) support per RFC 9180 #14126

Are you sure you want to change the base?

Add HPKE (Hybrid Public Key Encryption) support per RFC 9180 #14126

Uh oh!

Conversation

MkDev11 commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add HPKE (Hybrid Public Key Encryption) support per RFC 9180

Summary

What's Included

API Design

Design Decisions

Closes

Uh oh!

alex commented Jan 9, 2026

Uh oh!

MkDev11 commented Jan 9, 2026

Uh oh!

alex commented Jan 9, 2026

Uh oh!

alex commented Jan 10, 2026

Uh oh!

alex left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alex left a comment

Choose a reason for hiding this comment

Uh oh!

alex left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MkDev11 commented Jan 12, 2026

Uh oh!

alex commented Jan 12, 2026

Uh oh!

MkDev11 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alex commented Jan 12, 2026

Uh oh!

MkDev11 commented Jan 12, 2026

Uh oh!

MkDev11 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alex commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MkDev11 commented Jan 13, 2026

Uh oh!

alex commented Jan 19, 2026

Uh oh!

MkDev11 commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

MkDev11 commented Jan 9, 2026 •

edited

Loading

MkDev11 commented Jan 12, 2026 •

edited

Loading

MkDev11 commented Jan 12, 2026 •

edited

Loading