Skip to content

Commit e3088d6

Browse files
FiloSottilegopherbot
FiloSottile
authored and
gopherbot
committed
crypto/hpke: expose crypto/internal/hpke
Fixes #75300 Change-Id: I6a83e0d040dba3366819d2afff704f886a6a6964 Reviewed-on: https://go-review.googlesource.com/c/go/+/723560 Reviewed-by: Cherry Mui <cherryyz@google.com> Reviewed-by: Daniel McCarney <daniel@binaryparadox.net> Auto-Submit: Filippo Valsorda <filippo@golang.org> TryBot-Bypass: Filippo Valsorda <filippo@golang.org> Reviewed-by: Roland Shoemaker <roland@golang.org>
1 parent a5ebc6b commit e3088d6

File tree

15 files changed

+84
-23
lines changed

15 files changed

+84
-23
lines changed

‎api/next/75300.txt‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,54 @@ pkg crypto/ecdh, type KeyExchanger interface, ECDH(*PublicKey) ([]uint8, error)
1010
pkg crypto/ecdh, type KeyExchanger interface, PublicKey() *PublicKey #75300
1111
pkg crypto/mlkem, method (*DecapsulationKey1024) Encapsulator() crypto.Encapsulator #75300
1212
pkg crypto/mlkem, method (*DecapsulationKey768) Encapsulator() crypto.Encapsulator #75300
13+
pkg crypto/hpke, func AES128GCM() AEAD #75300
14+
pkg crypto/hpke, func AES256GCM() AEAD #75300
15+
pkg crypto/hpke, func ChaCha20Poly1305() AEAD #75300
16+
pkg crypto/hpke, func DHKEM(ecdh.Curve) KEM #75300
17+
pkg crypto/hpke, func ExportOnly() AEAD #75300
18+
pkg crypto/hpke, func HKDFSHA256() KDF #75300
19+
pkg crypto/hpke, func HKDFSHA384() KDF #75300
20+
pkg crypto/hpke, func HKDFSHA512() KDF #75300
21+
pkg crypto/hpke, func MLKEM1024() KEM #75300
22+
pkg crypto/hpke, func MLKEM1024P384() KEM #75300
23+
pkg crypto/hpke, func MLKEM768() KEM #75300
24+
pkg crypto/hpke, func MLKEM768P256() KEM #75300
25+
pkg crypto/hpke, func MLKEM768X25519() KEM #75300
26+
pkg crypto/hpke, func NewAEAD(uint16) (AEAD, error) #75300
27+
pkg crypto/hpke, func NewDHKEMPrivateKey(ecdh.KeyExchanger) (PrivateKey, error) #75300
28+
pkg crypto/hpke, func NewDHKEMPublicKey(*ecdh.PublicKey) (PublicKey, error) #75300
29+
pkg crypto/hpke, func NewHybridPrivateKey(crypto.Decapsulator, ecdh.KeyExchanger) (PrivateKey, error) #75300
30+
pkg crypto/hpke, func NewHybridPublicKey(crypto.Encapsulator, *ecdh.PublicKey) (PublicKey, error) #75300
31+
pkg crypto/hpke, func NewKDF(uint16) (KDF, error) #75300
32+
pkg crypto/hpke, func NewKEM(uint16) (KEM, error) #75300
33+
pkg crypto/hpke, func NewMLKEMPrivateKey(crypto.Decapsulator) (PrivateKey, error) #75300
34+
pkg crypto/hpke, func NewMLKEMPublicKey(crypto.Encapsulator) (PublicKey, error) #75300
35+
pkg crypto/hpke, func NewRecipient([]uint8, PrivateKey, KDF, AEAD, []uint8) (*Recipient, error) #75300
36+
pkg crypto/hpke, func NewSender(PublicKey, KDF, AEAD, []uint8) ([]uint8, *Sender, error) #75300
37+
pkg crypto/hpke, func Open(PrivateKey, KDF, AEAD, []uint8, []uint8) ([]uint8, error) #75300
38+
pkg crypto/hpke, func SHAKE128() KDF #75300
39+
pkg crypto/hpke, func SHAKE256() KDF #75300
40+
pkg crypto/hpke, func Seal(PublicKey, KDF, AEAD, []uint8, []uint8) ([]uint8, error) #75300
41+
pkg crypto/hpke, method (*Recipient) Export(string, int) ([]uint8, error) #75300
42+
pkg crypto/hpke, method (*Recipient) Open([]uint8, []uint8) ([]uint8, error) #75300
43+
pkg crypto/hpke, method (*Sender) Export(string, int) ([]uint8, error) #75300
44+
pkg crypto/hpke, method (*Sender) Seal([]uint8, []uint8) ([]uint8, error) #75300
45+
pkg crypto/hpke, type AEAD interface, ID() uint16 #75300
46+
pkg crypto/hpke, type AEAD interface, unexported methods #75300
47+
pkg crypto/hpke, type KDF interface, ID() uint16 #75300
48+
pkg crypto/hpke, type KDF interface, unexported methods #75300
49+
pkg crypto/hpke, type KEM interface, DeriveKeyPair([]uint8) (PrivateKey, error) #75300
50+
pkg crypto/hpke, type KEM interface, GenerateKey() (PrivateKey, error) #75300
51+
pkg crypto/hpke, type KEM interface, ID() uint16 #75300
52+
pkg crypto/hpke, type KEM interface, NewPrivateKey([]uint8) (PrivateKey, error) #75300
53+
pkg crypto/hpke, type KEM interface, NewPublicKey([]uint8) (PublicKey, error) #75300
54+
pkg crypto/hpke, type KEM interface, unexported methods #75300
55+
pkg crypto/hpke, type PrivateKey interface, Bytes() ([]uint8, error) #75300
56+
pkg crypto/hpke, type PrivateKey interface, KEM() KEM #75300
57+
pkg crypto/hpke, type PrivateKey interface, PublicKey() PublicKey #75300
58+
pkg crypto/hpke, type PrivateKey interface, unexported methods #75300
59+
pkg crypto/hpke, type PublicKey interface, Bytes() []uint8 #75300
60+
pkg crypto/hpke, type PublicKey interface, KEM() KEM #75300
61+
pkg crypto/hpke, type PublicKey interface, unexported methods #75300
62+
pkg crypto/hpke, type Recipient struct #75300
63+
pkg crypto/hpke, type Sender struct #75300

‎doc/next/6-stdlib/50-hpke.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### crypto/hpke
2+
3+
The new [crypto/hpke] package implements Hybrid Public Key Encryption
4+
(HPKE) as specified in [RFC 9180], including support for post-quantum
5+
hybrid KEMs.
6+
7+
[RFC 9180]: https://rfc-editor.org/rfc/rfc9180.html

‎doc/next/6-stdlib/99-minor/crypto/hpke/75300.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<!-- crypto/hpke is documented in its own section. -->

src/crypto/internal/hpke/aead.go renamed to src/crypto/hpke/aead.go

File renamed without changes.

src/crypto/internal/hpke/hpke.go renamed to src/crypto/hpke/hpke.go

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ package hpke
1010

1111
import (
1212
"crypto/cipher"
13-
"encoding/binary"
1413
"errors"
14+
"internal/byteorder"
1515
)
1616

1717
type context struct {
@@ -45,14 +45,14 @@ func newContext(sharedSecret []byte, kemID uint16, kdf KDF, aead AEAD, info []by
4545

4646
if kdf.oneStage() {
4747
secrets := make([]byte, 0, 2+2+len(sharedSecret))
48-
secrets = binary.BigEndian.AppendUint16(secrets, 0) // empty psk
49-
secrets = binary.BigEndian.AppendUint16(secrets, uint16(len(sharedSecret)))
48+
secrets = byteorder.BEAppendUint16(secrets, 0) // empty psk
49+
secrets = byteorder.BEAppendUint16(secrets, uint16(len(sharedSecret)))
5050
secrets = append(secrets, sharedSecret...)
5151

5252
ksContext := make([]byte, 0, 1+2+2+len(info))
53-
ksContext = append(ksContext, 0) // mode 0
54-
ksContext = binary.BigEndian.AppendUint16(ksContext, 0) // empty psk_id
55-
ksContext = binary.BigEndian.AppendUint16(ksContext, uint16(len(info)))
53+
ksContext = append(ksContext, 0) // mode 0
54+
ksContext = byteorder.BEAppendUint16(ksContext, 0) // empty psk_id
55+
ksContext = byteorder.BEAppendUint16(ksContext, uint16(len(info)))
5656
ksContext = append(ksContext, info...)
5757

5858
secret, err := kdf.labeledDerive(sid, secrets, "secret", ksContext,
@@ -245,7 +245,7 @@ func (r *Recipient) Export(exporterContext string, length int) ([]byte, error) {
245245

246246
func (ctx *context) nextNonce() []byte {
247247
nonce := make([]byte, ctx.aead.NonceSize())
248-
binary.BigEndian.PutUint64(nonce[len(nonce)-8:], ctx.seqNum)
248+
byteorder.BEPutUint64(nonce[len(nonce)-8:], ctx.seqNum)
249249
for i := range ctx.baseNonce {
250250
nonce[i] ^= ctx.baseNonce[i]
251251
}
@@ -255,8 +255,8 @@ func (ctx *context) nextNonce() []byte {
255255
func suiteID(kemID, kdfID, aeadID uint16) []byte {
256256
suiteID := make([]byte, 0, 4+2+2+2)
257257
suiteID = append(suiteID, []byte("HPKE")...)
258-
suiteID = binary.BigEndian.AppendUint16(suiteID, kemID)
259-
suiteID = binary.BigEndian.AppendUint16(suiteID, kdfID)
260-
suiteID = binary.BigEndian.AppendUint16(suiteID, aeadID)
258+
suiteID = byteorder.BEAppendUint16(suiteID, kemID)
259+
suiteID = byteorder.BEAppendUint16(suiteID, kdfID)
260+
suiteID = byteorder.BEAppendUint16(suiteID, aeadID)
261261
return suiteID
262262
}

src/crypto/internal/hpke/hpke_test.go renamed to src/crypto/hpke/hpke_test.go

File renamed without changes.

src/crypto/internal/hpke/kdf.go renamed to src/crypto/hpke/kdf.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ import (
99
"crypto/sha256"
1010
"crypto/sha3"
1111
"crypto/sha512"
12-
"encoding/binary"
1312
"errors"
1413
"fmt"
1514
"hash"
15+
"internal/byteorder"
1616
)
1717

1818
// The KDF is one of the three components of an HPKE ciphersuite, implementing
@@ -93,7 +93,7 @@ func (kdf *hkdfKDF) labeledExtract(suiteID []byte, salt []byte, label string, in
9393

9494
func (kdf *hkdfKDF) labeledExpand(suiteID []byte, randomKey []byte, label string, info []byte, length uint16) ([]byte, error) {
9595
labeledInfo := make([]byte, 0, 2+7+len(suiteID)+len(label)+len(info))
96-
labeledInfo = binary.BigEndian.AppendUint16(labeledInfo, length)
96+
labeledInfo = byteorder.BEAppendUint16(labeledInfo, length)
9797
labeledInfo = append(labeledInfo, []byte("HPKE-v1")...)
9898
labeledInfo = append(labeledInfo, suiteID...)
9999
labeledInfo = append(labeledInfo, label...)

src/crypto/internal/hpke/kem.go renamed to src/crypto/hpke/kem.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ package hpke
77
import (
88
"crypto/ecdh"
99
"crypto/rand"
10-
"encoding/binary"
1110
"errors"
11+
"internal/byteorder"
1212
)
1313

1414
// A KEM is a Key Encapsulation Mechanism, one of the three components of an
@@ -114,7 +114,7 @@ type dhKEM struct {
114114
}
115115

116116
func (kem *dhKEM) extractAndExpand(dhKey, kemContext []byte) ([]byte, error) {
117-
suiteID := binary.BigEndian.AppendUint16([]byte("KEM"), kem.id)
117+
suiteID := byteorder.BEAppendUint16([]byte("KEM"), kem.id)
118118
eaePRK, err := kem.kdf.labeledExtract(suiteID, nil, "eae_prk", dhKey)
119119
if err != nil {
120120
return nil, err
@@ -302,7 +302,7 @@ func (kem *dhKEM) NewPrivateKey(ikm []byte) (PrivateKey, error) {
302302

303303
func (kem *dhKEM) DeriveKeyPair(ikm []byte) (PrivateKey, error) {
304304
// DeriveKeyPair from RFC 9180 Section 7.1.3.
305-
suiteID := binary.BigEndian.AppendUint16([]byte("KEM"), kem.id)
305+
suiteID := byteorder.BEAppendUint16([]byte("KEM"), kem.id)
306306
prk, err := kem.kdf.labeledExtract(suiteID, nil, "dkp_prk", ikm)
307307
if err != nil {
308308
return nil, err

src/crypto/internal/hpke/pq.go renamed to src/crypto/hpke/pq.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ import (
1111
"crypto/mlkem"
1212
"crypto/rand"
1313
"crypto/sha3"
14-
"encoding/binary"
1514
"errors"
15+
"internal/byteorder"
1616
)
1717

1818
var mlkem768X25519 = &hybridKEM{
@@ -299,7 +299,7 @@ func newHybridPrivateKey(pq crypto.Decapsulator, t ecdh.KeyExchanger, seed []byt
299299
}
300300

301301
func (kem *hybridKEM) DeriveKeyPair(ikm []byte) (PrivateKey, error) {
302-
suiteID := binary.BigEndian.AppendUint16([]byte("KEM"), kem.id)
302+
suiteID := byteorder.BEAppendUint16([]byte("KEM"), kem.id)
303303
dk, err := SHAKE256().labeledDerive(suiteID, ikm, "DeriveKeyPair", nil, 32)
304304
if err != nil {
305305
return nil, err
@@ -496,7 +496,7 @@ func (kem *mlkemKEM) NewPrivateKey(priv []byte) (PrivateKey, error) {
496496
}
497497

498498
func (kem *mlkemKEM) DeriveKeyPair(ikm []byte) (PrivateKey, error) {
499-
suiteID := binary.BigEndian.AppendUint16([]byte("KEM"), kem.id)
499+
suiteID := byteorder.BEAppendUint16([]byte("KEM"), kem.id)
500500
dk, err := SHAKE256().labeledDerive(suiteID, ikm, "DeriveKeyPair", nil, 64)
501501
if err != nil {
502502
return nil, err

src/crypto/internal/hpke/testdata/hpke-pq.json renamed to src/crypto/hpke/testdata/hpke-pq.json

File renamed without changes.

0 commit comments

Comments
 (0)