Skip to content

[WIP]: Managed HPKE - #133804

Draft
vcsjones wants to merge 43 commits into
dotnet:mainfrom
vcsjones:hpke-impl
Draft

[WIP]: Managed HPKE#133804
vcsjones wants to merge 43 commits into
dotnet:mainfrom
vcsjones:hpke-impl

Conversation

@vcsjones

@vcsjones vcsjones commented Sep 12, 2026

Copy link
Copy Markdown
Member

This is the first commit for HPKE support.

  1. The public API is implemented
  2. This only has a managed implementation right now; OpenSSL and Windows-specific implementation is a follow up
  3. ML-KEM and Hybrid is not implemented yet.

vcsjones and others added 30 commits September 5, 2026 11:02
@vcsjones
Add experimental HPKE cipher suite descriptors
f8e9316 
Add HPKE algorithm identifiers, suite validation and equality, shared tests, and Microsoft.Bcl.Cryptography support.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Complete HpkeSuite metadata and public API
68258cf 
Add KEM, KDF, and AEAD metadata, expose suite sizes and names, implement ciphertext length calculation, and extend shared public API tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add managed HPKE foundation
939cd7d 
Add the initial Hpke API, managed algorithm support metadata, deterministic DHKEM key derivation and adapters for NIST curves and X25519.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Split managed HPKE KEM adapters
e87f872 
Move the base, ECDH, and X25519 KEM adapters into grouped source files and apply curve-specific candidate masking for deterministic scalar derivation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add HPKE key factory APIs
f57271e 
Implement random and deterministic HPKE key creation, resource ownership, reference declarations, and known-answer tests for DHKEM P-256, P-384, and X25519.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE decapsulation key export
fa21cda 
Forward private-key export through the KEM adapters, clear temporary secret buffers, and add public export coverage. Centralize factory support guards in Hpke while retaining backend-specific support queries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE encapsulation key export
d035fc0 
Expose public-key export through the KEM adapters, update reference declarations and tests, and clarify decapsulation-key export documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Checkpoint HPKE Seal and managed AEAD adapters
f589d5a 
Add public Seal scaffolding, KDF info-length validation, an AES-GCM adapter, and unsupported-platform dispatch. This is an intentionally incomplete, non-building checkpoint; SealCore remains unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add HPKE KEM encapsulation and key schedule adapters
e621f1c 
Implement DHKEM encapsulation, HKDF and SHAKE key schedules, and the ChaCha20-Poly1305 adapter. Centralize suite IDs and KEM labels, correct PRK slicing, and update Seal reference declarations. SealCore remains unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE single-shot sealing
ce437ba 
Connect KEM encapsulation, the Base-mode key schedule, and AEAD encryption, and split the AEAD adapters into their own files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Use stack buffers for fixed-size HPKE intermediates
7ea28a5 
Replace fixed-size crypto pool leases with bounded stack allocations and explicit secret clearing. Retain conditional pooling for variable-length KDF inputs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE single-shot opening
576af50 
Add the approved Open APIs, DHKEM decapsulation, Base-mode authenticated decryption, and reference declarations. Cover known-answer vectors, round trips, input validation, and authentication failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add abstract HPKE sender and recipient contexts
6e25e20 
Add the approved multi-shot base APIs, shared exporter limits, and CreateSender wrappers with managed and unsupported backend stubs. Include reference declarations and public wrapper coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement stateful HPKE sender creation and sealing
1b0907f 
Initialize sender contexts with fresh encapsulation and Base-mode secrets. Add sequence-derived nonces, exhaustion checks, AEAD ownership and cleanup, and public factory and lifetime coverage. Leave secret export unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement stateful HPKE recipient creation and opening
c2ff6cd 
Add approved CreateRecipient APIs and Base-mode recipient setup with sequence-derived nonces, authentication-failure recovery, and resource cleanup. Cover published multi-message vectors, validation, ordering and independent lifetimes. Leave secret export unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE PSK sender and recipient modes
cfc2d3b 
Add approved PSK factories with a 32-byte minimum key length, nonempty identifiers, and KDF-specific input limits. Share Base and PSK context setup and cover published vectors, mode separation, authentication failures, and independent lifetimes. Leave secret export unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement P-521 DHKEM support for HPKE
8f4fd22 
Add the approved KEM identifier, metadata, HKDF-SHA512 mapping, and P-521 scalar derivation. Increase bounded stack buffers and extend public coverage with published key and Base/PSK ciphertext vectors.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE context secret export
a798ae5 
Retain exporter secrets in fixed native memory and use the new span-capable UseKey overload for reference-protected exports. Remove nonce-only zeroing while preserving secret cleanup, and cover Base/PSK exporter vectors, length limits, sequencing and lifetimes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Implement HPKE key import APIs
4a10e1d 
Add approved encapsulation and decapsulation key import overloads with NIST scalar validation, raw X25519 import, and exception-safe adapter ownership. Cover known-answer keys, malformed input, public-only operations, and imported key lifetimes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Reject concurrent HPKE sender sealing
6f8aa63 
Guard the entire stateful SealCore operation with ConcurrencyBlock to prevent silent nonce reuse while preserving success-only sequence advancement.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Validate HPKE sender buffer overlaps
4152869 
Reject input/output and output/output overlap before sender core operations while permitting read-only input aliasing. Document overlapping-buffer exceptions and cover rejection before mutation and adjacent buffer handling.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Complete HPKE single-shot API documentation
9d8e8b6 
Document allocating Seal overloads and SealCore, and align buffer-length exception documentation with Open.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Fix HPKE target wiring in Microsoft.Bcl.Cryptography
0961d98 
Forward all HPKE types on .NET 11, use the unsupported implementation on .NET Framework, and omit HPKE from .NET 10 and .NET Standard. Add required resources and restrict the HashCode dependency to the Framework HPKE build.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Validate HPKE Open and Export buffer overlaps
6a80474 
Reject plaintext/input and exporter-context/destination overlap in public span overloads before invoking core operations. Document overlapping-buffer exceptions and cover rejection without mutation, empty spans and adjacent buffers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Refine HPKE validation order and temporary buffers
32f473c 
Validate arguments before disposal checks. Use bounded stack storage with allocation fallbacks for nonsecret KDF context buffers, retaining pooled handling for secret material. Cover disposed-input validation and the labeled-info stack threshold.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Remove redundant HPKE key-schedule output staging
850ea5f 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Stop clearing non-secret HPKE buffers
b26bfdd 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Derive HPKE KEM suite IDs from enum values
f0afdec 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Assert the internal HPKE export-length invariant
9badba1 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Reuse the KDF adapter across HPKE key operations
68535fa 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
vcsjones and others added 12 commits September 10, 2026 14:55
@vcsjones
Stream HPKE SHAKE inputs through public APIs
60e3a09 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Merge remote-tracking branch 'ms/main' into hpke-impl
52c1bc7
@vcsjones
Add shared HPKE contract tests
6624230 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add a representative HPKE test-vector corpus
eac840c 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Bound HPKE test exporter contexts to 1024 bytes
7dad5f4 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add shared HPKE sender and recipient contract tests
b2b0339 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add shared HPKE key tests and prune legacy tests
af31501 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Add shared HPKE implementation tests
a4318a9 
Replace legacy functional tests with shared corpus-driven coverage and simplify HPKE API documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Simplify HPKE recipient documentation
c37a857 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Simplify HPKE sender and suite documentation
93cf8e5 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Separate HPKE static validation from instance contracts
627779e 
Move static validation and unsupported-factory checks into shared fixtures, split null-argument and import-size tests, and share KEM test data.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones
Refine HPKE export tests and browser build exclusions
2d362f9 
Split export contract tests by key type and unroll invalid buffer-size checks. Exclude managed KEM adapters and AEAD support metadata from browser compilation, remove obsolete ECDH suppressions, and narrow the remaining AEAD pragmas.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5
@vcsjones vcsjones self-assigned this Sep 12, 2026
@vcsjones vcsjones added NO-REVIEW Experimental/testing PR, do NOT review it area-System.Security labels Sep 12, 2026
@azure-pipelines

azure-pipelines Bot commented Sep 12, 2026

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 4 pipeline(s).
12 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

@dotnet-policy-service

dotnet-policy-service Bot commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Tagging subscribers to this area: @bartonjs, @vcsjones, @dotnet/area-system-security
See info in area-owners.md if you want to be subscribed.

jkotas
jkotas reviewed Sep 13, 2026
View reviewed changes
Comment thread src/libraries/Common/src/System/Security/Cryptography/Hpke.cs
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.Diagnostics.CodeAnalysis;

@jkotas jkotas Sep 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these files rather live under System.Security.Cryprography?

Reshipping the implementation in the legacy Microsoft.Bcl.* package should not be a reason to move it under common.

I see we are inconsistent here. I think https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Bcl.AsyncInterfaces/src/Microsoft.Bcl.AsyncInterfaces.csproj or https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Bcl.Memory/src/Microsoft.Bcl.Memory.csproj are the right patterns to follow.

@vcsjones vcsjones Sep 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not always, I'll defer to @bartonjs if we want to try organizing our source different. It's a big departure from how we organize cryptography. We rely very heavily on partials. We don't have all the piece of HPKE in this PR so it's a bit "forward looking" here but usually the structure ends up being

  • Common/Hpke.cs
  • System.Security.Cryptography/src/Hpke.cs
  • Microsoft.Bcl.Cryptography/src/Hpke.cs

Because we use very different implementations between M.B.C. and S.S.C.

@jkotas jkotas Sep 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We rely very heavily on partials

Libraries depend heavily on partials. Partials are not a problem.

https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/project-guidelines.md#code-file-naming-conventions suggests using file name suffix for configuration specific slices of the partials, e.g. .netframework.cs, .downlevel.cs, .netcore.cs/.net.cs.

This was referenced Sep 13, 2026
Open
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jkotas jkotas jkotas left review comments
@jeffhandley jeffhandley Awaiting requested review from jeffhandley jeffhandley will be requested when the pull request is marked ready for review jeffhandley is a code owner
Copilot code review Copilot
Copilot will automatically review once the pull request is marked ready for review

At least 1 approving review is required to merge this pull request.

Assignees

@vcsjones vcsjones

Labels

area-System.Security NO-REVIEW Experimental/testing PR, do NOT review it

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vcsjones @jkotas