[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

Testing

tested with encap operation manually.
Testing generate + decap + seal + open
Code for manual testing: atulpatildbz@ac4b947

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

+	// 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

+		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

+	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).

NilanjanDaw · 2026-03-02T14:37:26Z

+		return
+	}
+
+	if req.Ciphertext.Algorithm != KemAlgorithmDHKEMX25519HKDFSHA256 {


Look up from protobuf instead of hardcoding?

…ine HTTP handler methods, and improve KEM algorithm validation.

pgonda · 2026-03-02T20:28:59Z

+	var outEncKey [32]byte
+	outEncKeyLen := C.size_t(len(outEncKey))
+	var outCT [48]byte // 32-byte secret + 16-byte GCM tag
+	outCTLen := C.size_t(len(outCT))


Size magics here? Can you define as file consts?

Added consts. Did the same in ws_key_custody_core_cgo.go‎ as well

pgonda · 2026-03-02T20:34:57Z

+// Open decrypts a sealed ciphertext using the binding key identified by
+// bindingUUID via Rust FFI (HPKE Open).
+// Returns the decrypted plaintext (shared secret).
+func Open(bindingUUID uuid.UUID, enc, ciphertext, aad []byte) ([]byte, error) {


No need to change now, but this PR is pretty large by my eyes. Open an Decap operations could have been separated into to smaller more targeted PRs.

Ack and apologies.
I didn't realize Decap + Open would grow to be so huge.

Thanks for taking the time to review

pgonda · 2026-03-02T20:35:38Z

+	)
+	if rc != 0 {
+		return nil, fmt.Errorf("key_manager_open failed with code %d", rc)
+	}


If RC isn't needed later. Typically in go we'd

if rc := ...; rc !=0 {
..
}

Makes sense. done

pgonda · 2026-03-02T20:37:07Z

+	}
+	aad := decapsAADContext(kemUUID, req.Ciphertext.Algorithm)
+
+	// Step 1: Look up the binding UUID for this KEM key.


Does this code base use this "Step #" comment format? If not please remove to be consistent

…ment - Extracts magic numbers for byte array sizes into file-level constants for better readability. - Refactors return code (rc) checks on C FFI calls to use idiomatic inline assignments. docs: remove 'Step #' prefix from comments

…chestration (google#650) * feat(keymanager): Implement Decap and Seal orchestration in Go * refactor: consolidate KeyProtectionService interfaces, explicitly define HTTP handler methods, and improve KEM algorithm validation. * review comments: refactor magic number and rc check, comments improvement - Extracts magic numbers for byte array sizes into file-level constants for better readability. - Refactors return code (rc) checks on C FFI calls to use idiomatic inline assignments. docs: remove 'Step #' prefix from comments * refactor: kps interface based DI for KCC

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

Merged

NilanjanDaw requested changes Feb 9, 2026

View reviewed changes

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

atulpatildbz force-pushed the wsd_decaps_go branch 7 times, most recently from 4deb925 to 448b861 Compare February 28, 2026 08:37

NilanjanDaw reviewed Mar 2, 2026

View reviewed changes

atulpatildbz force-pushed the wsd_decaps_go branch from 448b861 to 8f28a96 Compare March 2, 2026 15:13

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

38c67c6

atulpatildbz force-pushed the wsd_decaps_go branch from 8f28a96 to 38c67c6 Compare March 2, 2026 15:13

atulpatildbz requested a review from NilanjanDaw March 2, 2026 17:23

atulpatildbz force-pushed the wsd_decaps_go branch from 7cce446 to fde7312 Compare March 2, 2026 17:23

refactor: consolidate KeyProtectionService interfaces, explicitly def…

d987353

…ine HTTP handler methods, and improve KEM algorithm validation.

atulpatildbz force-pushed the wsd_decaps_go branch from fde7312 to d987353 Compare March 2, 2026 17:47

jkl73 requested a review from pgonda March 2, 2026 19:31

pgonda reviewed Mar 2, 2026

View reviewed changes

atulpatildbz force-pushed the wsd_decaps_go branch from e8d98ec to 1ce8149 Compare March 3, 2026 06:45

NilanjanDaw reviewed Mar 3, 2026

View reviewed changes

Comment thread keymanager/key_protection_service/service.go

NilanjanDaw self-requested a review March 3, 2026 09:12

atulpatildbz force-pushed the wsd_decaps_go branch from 1ce8149 to 7af1241 Compare March 3, 2026 09:25

refactor: kps interface based DI for KCC

bbc84b0

atulpatildbz force-pushed the wsd_decaps_go branch from 7af1241 to bbc84b0 Compare March 3, 2026 09:33

NilanjanDaw approved these changes Mar 3, 2026

View reviewed changes

atulpatildbz merged commit cbbc624 into google:main Mar 3, 2026
12 checks passed

BrewTestBot mentioned this pull request Mar 13, 2026

gotpm 0.4.8 Homebrew/homebrew-core#272213

Merged

Conversation

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

Uh oh!

Testing

Uh oh!

NilanjanDaw left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atulpatildbz commented Feb 13, 2026

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!

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!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

atulpatildbz commented Feb 9, 2026 •

edited

Loading

atulpatildbz Feb 13, 2026 •

edited

Loading