[KeyManager] Implement FFIs for decap-and-seal and HPKE open operations by NilanjanDaw · Pull Request #649 · google/go-tpm-tools

NilanjanDaw · 2026-02-08T19:47:23Z

This PR implements the core FFI interfaces for the Key Protection Service (KPS) and Workload Service (WS) to support the secure secret delivery flow using the decap-and-seal and HPKE open operations. It also introduces necessary cryptographic utilities to test the end-to-end secret sharing flow.

Key Changes

km_common (Common Crypto & Utilities)

DHKEM Encapsulation: Added a "test-only" encap to support encapsulation operation flows with a pre-shared key. This manually implements the Encap operation as BoringSSL's current FFI lacks a direct entry point encapsulation.
Test Infrastructure: Introduced a test-utils feature to allow these cryptographic helpers to be shared across crates for testing purposes without exposing them in production builds.

kps_key_custody_core (Key Protection Service)

key_manager_decap_and_seal FFI: Implemented the decapsulate-and-seal logic. This takes a client's encapsulated key, recovers the shared secret using the KEM private key, and immediately reseals it for the target Workload Service using its binding public key.

ws_key_custody_core (Workload Service)

key_manager_open FFI: Implemented the final decryption step. It retrieves the Binding Private Key (isolated in memfd_secret backed storage) to decrypt the final payload delivered from the KPS.

Testing Performed

Ran cargo test -p km_common
Ran cargo test -p kps_key_custody_core
Ran cargo test -p ws_key_custody_core
All 40+ unit tests across the workspace are passing.

keymanager/km_common/src/key_types.rs

keymanager/km_common/src/crypto.rs

keymanager/key_protection_service/key_custody_core/src/lib.rs

This change functions as the Go-side implementation for the Decap and Seal flow. It is based on PR google#652 (Key Gen) and PR google#649 (FFI Decap). Base Commit: 2030fa6 (Align Key Generation API with contract) Squashed Commits: - Fix compilation and tests for wsd_decaps_go (API alignment to /v1/keys:decap) - keymanager/wsd: align decaps payloads with proto messages - keymanager/wsd: define decaps API proto schema - [keymanager/wsd] Add /keys:decaps endpoint with DecapAndSeal + Open orchestration Key Features: - endpoint: POST /v1/keys:decap - Request: DecapsRequest (snake_case) - Response: DecapsResponse (snake_case) - Flows: DecapAndSeal (KPS) -> Open (WSD)

keymanager/key_protection_service/key_custody_core/src/lib.rs

keymanager/workload_service/key_custody_core/src/lib.rs

keymanager/key_protection_service/key_custody_core/src/lib.rs

Introduces `key_manager_decap_and_seal`, a new FFI function in `key_custody_core` that enables decapsulating a shared secret and immediately resealing it with a binding public key. Key Changes: - New FFI: Added `key_manager_decap_and_seal` to handle the transition of a shared secret from a client-provided encapsulation to a sealed form bound to a specific receiver. - Security: Integrated `zeroize` to ensure the intermediate shared secret is wiped from memory after the resealing operation. - Error Handling: Implemented robust error reporting for invalid inputs, missing keys, and cryptographic failures. - Testing: Added a comprehensive unit test `test_decap_and_seal_success` that simulates a client-to-service flow and verifies the recovered secret.

BoringSSL does not currently expose a way to initialize a RecipientContext directly from a pre-calculated shared secret. This change adds a helper to km_common that manually implements the HPKE KeySchedule to derive the AEAD key and nonce. Changes: - Implement and HPKE KDF helpers in km_common. - Mark these helpers as available only for tests or via the new feature. - Enable in kps_key_custody_core dev-dependencies. - Update to verify decryption using the recovered secret.

This change adds the FFI function to the workload service's key custody core. This function allows the Workload Service to decrypt secrets using a previously generated binding key. Key features: - Look up the Binding Private Key from the registry (isolated in its own memfd_secret page via Vault). - Perform an HPKE open operation to decrypt the provided payload. - Aggressively sanitize sensitive material by zeroing out decrypted plaintext buffers after copying to the output. - Add comprehensive unit tests covering success, invalid UUID, and insufficient buffer size scenarios. - Fix unused import warnings in km_common related to test-only crypto helpers.

keymanager/key_protection_service/key_custody_core/src/lib.rs

clundin25 · 2026-02-19T20:31:09Z

keymanager/key_protection_service/key_custody_core/src/lib.rs

-        Err(e) => e,
-    }
+    }))
+    .unwrap_or(-1)


The FFI API has a pretty opaque error code interface. Any future plans for improving this?

Once pattern I've seen before is setting a global ERRNO with an error code for the last failure, and always returning -1 in the FFI API.

Let me do this in a future PR. We will track this in #668

keymanager/key_protection_service/key_custody_core/src/lib.rs

clundin25 · 2026-02-19T20:48:33Z

keymanager/key_protection_service/key_custody_core/Cargo.toml

+
+[dev-dependencies]
+km_common = { path = "../../km_common", features = ["test-utils"] }


It might be useful to use a "Cargo workspace" to manage all of these shared crates:

https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html

Done, updated the cargo dependencies to a workspace.

atulpatildbz · 2026-02-20T12:07:36Z

keymanager/key_protection_service/key_custody_core/src/lib.rs

 use km_common::key_types::{KeyRecord, KeyRegistry, KeySpec};
 use prost::Message;
 use std::slice;
-use std::sync::atomic::AtomicBool;


nit: can you format this file? i think the previous position of this import was correct

atulpatildbz · 2026-02-20T13:36:09Z

keymanager/key_protection_service/key_custody_core/src/lib.rs

+    uuid: Uuid,
+    encapsulated_key: &[u8],
+    aad: &[u8],
+) -> Result<(Vec<u8>, Vec<u8>), i32> {


should we avoid the intermediate allocation and accept &mut [u8] instead? since caller already provides out_encapsulated_key, out_ciphertext output buffers

atulpatildbz · 2026-02-20T13:39:46Z

keymanager/key_protection_service/key_custody_core/src/lib.rs

-        Some(_) => 0, // Success
-        None => -1,   // Not found
+    // Seal
+    match km_common::crypto::hpke_seal(binding_public_key, &shared_secret, aad, hpke_algo) {


we're using hpke_algo here. which assumes that binding key always supports the exact same cryptro params (KEM/KDF/AEAD) as the KEM key.

is your comment of the other PR #665 (comment) valid here?

atulpatildbz · 2026-02-20T13:40:42Z

keymanager/workload_service/key_custody_core/src/lib.rs

-        None => -1,   // Not found
+/// Internal function to decrypt a ciphertext using a stored binding key.
+fn open_internal(uuid: Uuid, enc: &[u8], ciphertext: &[u8], aad: &[u8]) -> Result<SecretBox, i32> {
+    let Some(record) = KEY_REGISTRY.get_key(&uuid) else {


nit: we can use shorter idiom here:

let key_record = KEY_REGISTRY.get_key(&uuid).ok_or(-1)?;

atulpatildbz · 2026-02-20T15:02:43Z

keymanager/workload_service/key_custody_core/src/lib.rs

+/// * `out_plaintext_len` - The size of `out_plaintext` buffer.
+///   On success, it will be updated with the actual size of the plaintext.


the signature is :

out_plaintext_len: usize, // Passed by value!

this statement is misleading: "On success, it will be updated with the actual size of the plaintext". since it's passed by value.

check if you need to update the signature to *mut usize. or fix the docstring

NilanjanDaw force-pushed the add-decap-seal-open-ffi branch from 49aeabd to 20bc382 Compare February 8, 2026 21:02

NilanjanDaw requested a review from atulpatildbz February 9, 2026 07:27

This was referenced Feb 9, 2026

[keymanager/wsd] Add /keys:decaps KOL API with DecapAndSeal + Open orchestration #650

Open

[keymanager/wsd] Add /keys:destroy Go KOL handler with KEM + binding key destruction #651

Open

bluegate010 reviewed Feb 9, 2026

View reviewed changes

keymanager/km_common/src/key_types.rs Outdated Show resolved Hide resolved

bluegate010 reviewed Feb 10, 2026

View reviewed changes

bluegate010 mentioned this pull request Feb 10, 2026

[KeyManager] Add HPKE and DHKEM crypto primitives #643

Merged

NilanjanDaw force-pushed the add-decap-seal-open-ffi branch from 20bc382 to cb4a8ec Compare February 15, 2026 11:00

NilanjanDaw changed the title ~~Implement Key Manager FFIs for decap-and-seal and HPKE open operations~~ [KeyManager] Implement Key Manager FFIs for decap-and-seal and HPKE open operations Feb 15, 2026

NilanjanDaw changed the title ~~[KeyManager] Implement Key Manager FFIs for decap-and-seal and HPKE open operations~~ [KeyManager] Implement FFIs for decap-and-seal and HPKE open operations Feb 15, 2026

atulpatildbz reviewed Feb 15, 2026

View reviewed changes

NilanjanDaw mentioned this pull request Feb 17, 2026

[KeyManager] Reduce KeyRegistry complexity #667

Open

NilanjanDaw force-pushed the add-decap-seal-open-ffi branch from cb4a8ec to a7336b2 Compare February 18, 2026 07:23

bluegate010 reviewed Feb 19, 2026

View reviewed changes

keymanager/key_protection_service/key_custody_core/src/lib.rs Show resolved Hide resolved

keymanager/key_protection_service/key_custody_core/src/lib.rs Show resolved Hide resolved

NilanjanDaw requested review from atulpatildbz, bluegate010, clundin25 and zhalvorsen February 19, 2026 20:11

NilanjanDaw added 10 commits February 19, 2026 20:14

Added more unit tests for decap and seal

3916e07

code refactor for clippy and lint warnings.

dcd658b

upgrade crypto lib to SecretBox feature

66857f3

fix codebase to use secretbox, tighten security

1bce297

minor rebase fix

79f32bb

address review comments

6c4790a

separate unsafe functions from business logic

1104d79

clundin25 reviewed Feb 19, 2026

View reviewed changes

keymanager/key_protection_service/key_custody_core/src/lib.rs Outdated Show resolved Hide resolved

clundin25 reviewed Feb 19, 2026

View reviewed changes

keymanager/key_protection_service/key_custody_core/src/lib.rs Outdated Show resolved Hide resolved

clundin25 reviewed Feb 19, 2026

View reviewed changes

keymanager/key_protection_service/key_custody_core/src/lib.rs Outdated Show resolved Hide resolved

clundin25 reviewed Feb 19, 2026

View reviewed changes

resolve review comments

036d7f6

NilanjanDaw force-pushed the add-decap-seal-open-ffi branch from b653fa6 to 036d7f6 Compare February 20, 2026 11:47

NilanjanDaw requested a review from clundin25 February 20, 2026 11:51

atulpatildbz reviewed Feb 20, 2026

View reviewed changes


		[dev-dependencies]
		km_common = { path = "../../km_common", features = ["test-utils"] }

		/// * `out_plaintext_len` - The size of `out_plaintext` buffer.
		/// On success, it will be updated with the actual size of the plaintext.

Comments

Conversation

NilanjanDaw commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

NilanjanDaw commented Feb 8, 2026 •

edited

Loading