From: Filippo Valsorda <filippo@golang.org>
Date: Mon, 22 Sep 2025 12:12:53 +0000 (+0200)
Subject: crypto: add Encapsulator and Decapsulator interfaces
X-Git-Tag: go1.26rc1~236
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=a2946f2385;p=gostls13.git

crypto: add Encapsulator and Decapsulator interfaces

Updates #75300

Change-Id: I6a6a6964a0ab36ee3132d8481515c34c86011c13
Reviewed-on: https://go-review.googlesource.com/c/go/+/705796
Reviewed-by: Mark Freeman <markfreeman@google.com>
Reviewed-by: Daniel McCarney <daniel@binaryparadox.net>
Reviewed-by: Junyang Shao <shaojunyang@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
---

diff --git a/api/next/75300.txt b/api/next/75300.txt
index 9bc1e7f5db..da24eb4aa3 100644
--- a/api/next/75300.txt
+++ b/api/next/75300.txt
@@ -1,4 +1,12 @@
+pkg crypto, type Decapsulator interface { Decapsulate, Encapsulator } #75300
+pkg crypto, type Decapsulator interface, Decapsulate([]uint8) ([]uint8, error) #75300
+pkg crypto, type Decapsulator interface, Encapsulator() Encapsulator #75300
+pkg crypto, type Encapsulator interface { Bytes, Encapsulate } #75300
+pkg crypto, type Encapsulator interface, Bytes() []uint8 #75300
+pkg crypto, type Encapsulator interface, Encapsulate() ([]uint8, []uint8) #75300
 pkg crypto/ecdh, type KeyExchanger interface { Curve, ECDH, PublicKey } #75300
 pkg crypto/ecdh, type KeyExchanger interface, Curve() Curve #75300
 pkg crypto/ecdh, type KeyExchanger interface, ECDH(*PublicKey) ([]uint8, error) #75300
 pkg crypto/ecdh, type KeyExchanger interface, PublicKey() *PublicKey #75300
+pkg crypto/mlkem, method (*DecapsulationKey1024) Encapsulator() crypto.Encapsulator #75300
+pkg crypto/mlkem, method (*DecapsulationKey768) Encapsulator() crypto.Encapsulator #75300
diff --git a/doc/next/6-stdlib/99-minor/crypto/75300.md b/doc/next/6-stdlib/99-minor/crypto/75300.md
new file mode 100644
index 0000000000..02418ea371
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/crypto/75300.md
@@ -0,0 +1,2 @@
+The new [Encapsulator] and [Decapsulator] interfaces allow accepting abstract
+KEM encapsulation or decapsulation keys.
diff --git a/doc/next/6-stdlib/99-minor/crypto/mlkem/75300.md b/doc/next/6-stdlib/99-minor/crypto/mlkem/75300.md
new file mode 100644
index 0000000000..c9cf95f01b
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/crypto/mlkem/75300.md
@@ -0,0 +1,3 @@
+The new [DecapsulationKey768.Encapsulator] and
+[DecapsulationKey1024.Encapsulator] methods implement the new
+[crypto.Decapsulator] interface.
diff --git a/src/crypto/crypto.go b/src/crypto/crypto.go
index 6b3db5a1a3..0bf9ec834b 100644
--- a/src/crypto/crypto.go
+++ b/src/crypto/crypto.go
@@ -253,3 +253,21 @@ func SignMessage(signer Signer, rand io.Reader, msg []byte, opts SignerOpts) (si
 	}
 	return signer.Sign(rand, msg, opts)
 }
+
+// Decapsulator is an interface for an opaque private KEM key that can be used for
+// decapsulation operations. For example, an ML-KEM key kept in a hardware module.
+//
+// It is implemented, for example, by [crypto/mlkem.DecapsulationKey768].
+type Decapsulator interface {
+	Encapsulator() Encapsulator
+	Decapsulate(ciphertext []byte) (sharedKey []byte, err error)
+}
+
+// Encapsulator is an interface for a public KEM key that can be used for
+// encapsulation operations.
+//
+// It is implemented, for example, by [crypto/mlkem.EncapsulationKey768].
+type Encapsulator interface {
+	Bytes() []byte
+	Encapsulate() (sharedKey, ciphertext []byte)
+}
diff --git a/src/crypto/mlkem/mlkem.go b/src/crypto/mlkem/mlkem.go
index cb44bede20..176b79673b 100644
--- a/src/crypto/mlkem/mlkem.go
+++ b/src/crypto/mlkem/mlkem.go
@@ -11,7 +11,10 @@
 // [NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
 package mlkem
 
-import "crypto/internal/fips140/mlkem"
+import (
+	"crypto"
+	"crypto/internal/fips140/mlkem"
+)
 
 const (
 	// SharedKeySize is the size of a shared key produced by ML-KEM.
@@ -82,6 +85,16 @@ func (dk *DecapsulationKey768) EncapsulationKey() *EncapsulationKey768 {
 	return &EncapsulationKey768{dk.key.EncapsulationKey()}
 }
 
+// Encapsulator returns the encapsulation key, like
+// [DecapsulationKey768.EncapsulationKey].
+//
+// It implements [crypto.Decapsulator].
+func (dk *DecapsulationKey768) Encapsulator() crypto.Encapsulator {
+	return dk.EncapsulationKey()
+}
+
+var _ crypto.Decapsulator = (*DecapsulationKey768)(nil)
+
 // An EncapsulationKey768 is the public key used to produce ciphertexts to be
 // decapsulated by the corresponding DecapsulationKey768.
 type EncapsulationKey768 struct {
@@ -164,6 +177,16 @@ func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 {
 	return &EncapsulationKey1024{dk.key.EncapsulationKey()}
 }
 
+// Encapsulator returns the encapsulation key, like
+// [DecapsulationKey1024.EncapsulationKey].
+//
+// It implements [crypto.Decapsulator].
+func (dk *DecapsulationKey1024) Encapsulator() crypto.Encapsulator {
+	return dk.EncapsulationKey()
+}
+
+var _ crypto.Decapsulator = (*DecapsulationKey1024)(nil)
+
 // An EncapsulationKey1024 is the public key used to produce ciphertexts to be
 // decapsulated by the corresponding DecapsulationKey1024.
 type EncapsulationKey1024 struct {