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 9bc1e7f5dbb68b9ae8314a866f6bf48be6562e59..da24eb4aa341374be9bd14fb2d7a91e18d9d3f06 100644 (file)
--- 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 (file)
index 0000000..02418ea
--- /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 (file)
index 0000000..c9cf95f
--- /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 6b3db5a1a387f72833149ad29e15383ba79b278b..0bf9ec834b7d910f23990e133b6caeea5c575012 100644 (file)
--- 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 cb44bede20b72cc1c46ed4c11664c51349cecd49..176b79673b08512287cc80efc3cd73e7ed888e18 100644 (file)
--- 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 {