[keymanager/wsd] Add /keys:decaps KOL API with DecapAndSeal + Open orchestration by atulpatildbz · Pull Request #650 · google/go-tpm-tools

atulpatildbz · 2026-02-09T08:51:05Z

Implements the Go orchestration layer (KOL) for POST /v1/keys:decap. This key exchange endpoint allows workloads to recover a shared secret from a KEM encapsulation.

Flow:

Workload sends {key_handle, ciphertext: {algorithm, ciphertext}} to WSD
WSD looks up binding UUID from the KEM→Binding map (populated during /v1/keys:generate_kem)
WSD calls KPS DecapAndSeal — decapsulates the shared secret using the KEM private key, reseals it with the binding public key
WSD calls WSD KCC Open — unseals the shared secret using the binding private key
WSD returns the plaintext shared secret (base64-encoded) to the workload

Changes:

Endpoint: Added POST /v1/keys:decap (aligned with API contract)
JSON: Used snake_case for JSON fields in DecapsRequest and DecapsResponse
C headers: Added key_manager_decap_and_seal (KPS) and key_manager_open (WSD) declarations
CGO bridges: Added DecapAndSeal() and Open() Go wrappers for the Rust FFI functions
KPS service: Extended Service with DecapAndSeal method
WSD server: Added DecapSealer/Opener interfaces, handleDecaps handler
Tests: Verified with TestHandleDecapsSuccess in and Rust unit tests

Dependencies

This PR is built on top of:

PR [KeyManager] Implement FFIs for decap-and-seal and HPKE open operations #649 (FFI Decap)
PR [keymanager/wsd] Add Go orchestration layer (KOL) for WSD key generation #652 (Key Gen Go)

PR #652 ends at commit 2030fa6.

What to review

Please review commits from 4f935f5 onwards (after base commit 2030fa6).
The entire Decap implementation is squashed into this single commit:

4f935f5 feat(keymanager): Implement Decap and Seal orchestration in Go

All commits prior to 4f935f5 are from PR #652 and PR #649 (already under separate review).

NilanjanDaw

Thanks for the PR. Over-all comment: I think we need to align the message formats for the APIs. Lets define them in a separate proto file, so that they can be easily reviewed.

NilanjanDaw · 2026-02-09T10:53:07Z

keymanager/workload_service/key_custody_core/ws_key_custody_core_cgo.go

+	// Use a sentinel byte so the pointer is always valid.
+	var aadSentinel [1]byte
+	aadPtr := (*C.uint8_t)(unsafe.Pointer(&aadSentinel[0]))
+	aadLen := C.size_t(0)
+	if len(aad) > 0 {
+		aadPtr = (*C.uint8_t)(unsafe.Pointer(&aad[0]))
+		aadLen = C.size_t(len(aad))
+	}


Should we add a AAD context for the HPKE seal/open operation?

Good point. I added an explicit AAD context for the decaps flow and pass it through both KPS DecapAndSeal and WSD Open: "wsd:keys:decaps:v1::". Addressed in commit 02d8655.

NilanjanDaw · 2026-02-09T10:57:17Z

keymanager/workload_service/server.go

+		return
+	}
+
+	encapsulatedKey, err := base64.StdEncoding.DecodeString(req.EncapsulatedKey)


I think we need to align the message format and the params a bit. The encapsulatedKey is expected to be raw bytes and packed as below

message DecapsRequest { KeyHandle key_handle = 1; KemCiphertext ciphertext = 2; } // The results of an Encaps operation. message KemCiphertext { KemAlgorithm algorithm = 1; bytes ciphertext = 2; // `Nenc` bytes long. }

Updated to the requested shape: DecapsRequest{ keyHandle, ciphertext{ algorithm, ciphertext } }.
The proto contract is in keymanager/workload_service/proto/key_management.proto (commit 4d604da), and handler parsing/validation was updated in commit 02d8655.

NilanjanDaw · 2026-02-09T11:02:34Z

keymanager/workload_service/server.go

+	resp := DecapsResponse{
+		SharedSecret: base64.StdEncoding.EncodeToString(plaintext),
+	}


Response should be encoded as follows

// The results of a Decaps operation. message KemSharedSecret { KemAlgorithm algorithm = 1; bytes secret = 2; // `Nsecret` bytes long. }

Updated response encoding to KemSharedSecret shape: sharedSecret{ algorithm, secret }. Implemented in commit 02d8655 (including test updates).

atulpatildbz · 2026-02-13T13:46:00Z

Thanks for the PR. Over-all comment: I think we need to align the message formats for the APIs. Lets define them in a separate proto file, so that they can be easily reviewed.

Thanks for the review. I aligned the API message formats and added a dedicated proto file: keymanager/workload_service/proto/key_management.proto (commit 4d604da). I then updated the WSD /keys:decaps handler/tests to use that proto-shaped payload/response (commit 02d8655).

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.

This change introduces automated C header generation using binding and fixes a critical ABI mismatch in the key custody FFI layer. Changes: 1. FFI Header Generation: - Added keymanager/generate_ffi_headers.sh script to generate C headers for all key custody components. - Added cbindgen.toml configurations for km_common, kps_key_custody_core, and ws_key_custody_core. - Exposed km_common::ffi with stable C-ABI structs and constants to ensure compatibility. 2. FFI ABI Safety Fix: - Problem: Previous FFI functions accepted HpkeAlgorithm (Protobuf-generated repr(Rust) struct) by value. This caused undefined behavior as C callers expected a C-compatible layout. - Fix: Updated key_manager_generate_kem_keypair and key_manager_generate_binding_keypair to accept KmHpkeAlgorithm, a dedicated repr(C) struct. - Mechanism: Implemented safe conversion (impl From<KmHpkeAlgorithm> for HpkeAlgorithm) to bridge the FFI boundary safely. - Verification: Added FFI-specific tests covering KmHpkeAlgorithm usage.

- Implement binding and KEM key generation endpoints in Workload Service. - Add Key Protection Service client integration. - Adapt Go CGO wrappers to match new Rust FFI signatures (KmHpkeAlgorithm, usize). - Add component integration tests (Go Service -> Rust Core) to verify FFI flow.

Updates the EnumerateKEMKeys API to use snake_case JSON tags and string serialization for enums (KemAlgorithm, KeyProtectionMechanism) to align with the defined API contract.

- Update GenerateKemRequest and GenerateKemResponse JSON tags to use snake_case. - Update KemAlgorithm enum string representation to remove KEM_ALGORITHM_ prefix. - Update tests to reflect these changes.

This change implements the Decap and Seal flow in the Workload Service. It includes: - POST /v1/keys:decap endpoint - DecapAndSeal (KPS) and Open (WSD) orchestration - AAD binding for decapsulation - DecapsRequest and DecapsResponse proto definitions - FFI integration for Decap and Seal

atulpatildbz requested a review from NilanjanDaw February 9, 2026 08:51

atulpatildbz mentioned this pull request Feb 9, 2026

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

Open

NilanjanDaw requested changes Feb 9, 2026

View reviewed changes

NilanjanDaw and others added 9 commits February 15, 2026 09:43

Added more unit tests for decap and seal

ec43778

code refactor for clippy and lint warnings.

a860d90

workload_service: align key generation API with contract

42f99cb

Updates the EnumerateKEMKeys API to use snake_case JSON tags and string serialization for enums (KemAlgorithm, KeyProtectionMechanism) to align with the defined API contract.

Align Key Generation API with contract

2030fa6

- Update GenerateKemRequest and GenerateKemResponse JSON tags to use snake_case. - Update KemAlgorithm enum string representation to remove KEM_ALGORITHM_ prefix. - Update tests to reflect these changes.

atulpatildbz force-pushed the wsd_decaps_go branch 4 times, most recently from bc9f760 to acab338 Compare February 15, 2026 10:54

atulpatildbz force-pushed the wsd_decaps_go branch from acab338 to 4f935f5 Compare February 15, 2026 10:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

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

[keymanager/wsd] Add /keys:decaps KOL API with DecapAndSeal + Open orchestration#650
atulpatildbz wants to merge 10 commits intogoogle:mainfrom
atulpatildbz:wsd_decaps_go

atulpatildbz commented Feb 9, 2026 •

edited

Loading

Uh oh!

NilanjanDaw left a comment

Uh oh!

NilanjanDaw Feb 9, 2026

Uh oh!

atulpatildbz Feb 13, 2026

Uh oh!

NilanjanDaw Feb 9, 2026

Uh oh!

atulpatildbz Feb 13, 2026 •

edited

Loading

Uh oh!

NilanjanDaw Feb 9, 2026

Uh oh!

atulpatildbz Feb 13, 2026

Uh oh!

atulpatildbz commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

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

Uh oh!

Dependencies

What to review

Uh oh!

NilanjanDaw left a comment

Choose a reason for hiding this comment

Uh oh!

NilanjanDaw Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

atulpatildbz Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

NilanjanDaw Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NilanjanDaw Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

atulpatildbz Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

atulpatildbz commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

atulpatildbz commented Feb 9, 2026 •

edited

Loading

atulpatildbz Feb 13, 2026 •

edited

Loading