// Copyright 2024 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. package hpke import ( "crypto" "crypto/aes" "crypto/cipher" "crypto/ecdh" "crypto/rand" "encoding/binary" "errors" "math/bits" "golang.org/x/crypto/chacha20poly1305" "golang.org/x/crypto/hkdf" ) // testingOnlyGenerateKey is only used during testing, to provide // a fixed test key to use when checking the RFC 9180 vectors. var testingOnlyGenerateKey func() (*ecdh.PrivateKey, error) type hkdfKDF struct { hash crypto.Hash } func (kdf *hkdfKDF) LabeledExtract(suiteID []byte, salt []byte, label string, inputKey []byte) []byte { labeledIKM := make([]byte, 0, 7+len(suiteID)+len(label)+len(inputKey)) labeledIKM = append(labeledIKM, []byte("HPKE-v1")...) labeledIKM = append(labeledIKM, suiteID...) labeledIKM = append(labeledIKM, label...) labeledIKM = append(labeledIKM, inputKey...) return hkdf.Extract(kdf.hash.New, labeledIKM, salt) } func (kdf *hkdfKDF) LabeledExpand(suiteID []byte, randomKey []byte, label string, info []byte, length uint16) []byte { labeledInfo := make([]byte, 0, 2+7+len(suiteID)+len(label)+len(info)) labeledInfo = binary.BigEndian.AppendUint16(labeledInfo, length) labeledInfo = append(labeledInfo, []byte("HPKE-v1")...) labeledInfo = append(labeledInfo, suiteID...) labeledInfo = append(labeledInfo, label...) labeledInfo = append(labeledInfo, info...) out := make([]byte, length) n, err := hkdf.Expand(kdf.hash.New, randomKey, labeledInfo).Read(out) if err != nil || n != int(length) { panic("hpke: LabeledExpand failed unexpectedly") } return out } // dhKEM implements the KEM specified in RFC 9180, Section 4.1. type dhKEM struct { dh ecdh.Curve kdf hkdfKDF suiteID []byte nSecret uint16 } var SupportedKEMs = map[uint16]struct { curve ecdh.Curve hash crypto.Hash nSecret uint16 }{ // RFC 9180 Section 7.1 0x0020: {ecdh.X25519(), crypto.SHA256, 32}, } func newDHKem(kemID uint16) (*dhKEM, error) { suite, ok := SupportedKEMs[kemID] if !ok { return nil, errors.New("unsupported suite ID") } return &dhKEM{ dh: suite.curve, kdf: hkdfKDF{suite.hash}, suiteID: binary.BigEndian.AppendUint16([]byte("KEM"), kemID), nSecret: suite.nSecret, }, nil } func (dh *dhKEM) ExtractAndExpand(dhKey, kemContext []byte) []byte { eaePRK := dh.kdf.LabeledExtract(dh.suiteID[:], nil, "eae_prk", dhKey) return dh.kdf.LabeledExpand(dh.suiteID[:], eaePRK, "shared_secret", kemContext, dh.nSecret) } func (dh *dhKEM) Encap(pubRecipient *ecdh.PublicKey) (sharedSecret []byte, encapPub []byte, err error) { var privEph *ecdh.PrivateKey if testingOnlyGenerateKey != nil { privEph, err = testingOnlyGenerateKey() } else { privEph, err = dh.dh.GenerateKey(rand.Reader) } if err != nil { return nil, nil, err } dhVal, err := privEph.ECDH(pubRecipient) if err != nil { return nil, nil, err } encPubEph := privEph.PublicKey().Bytes() encPubRecip := pubRecipient.Bytes() kemContext := append(encPubEph, encPubRecip...) return dh.ExtractAndExpand(dhVal, kemContext), encPubEph, nil } type Sender struct { aead cipher.AEAD kem *dhKEM sharedSecret []byte suiteID []byte key []byte baseNonce []byte exporterSecret []byte seqNum uint128 } var aesGCMNew = func(key []byte) (cipher.AEAD, error) { block, err := aes.NewCipher(key) if err != nil { return nil, err } return cipher.NewGCM(block) } var SupportedAEADs = map[uint16]struct { keySize int nonceSize int aead func([]byte) (cipher.AEAD, error) }{ // RFC 9180, Section 7.3 0x0001: {keySize: 16, nonceSize: 12, aead: aesGCMNew}, 0x0002: {keySize: 32, nonceSize: 12, aead: aesGCMNew}, 0x0003: {keySize: chacha20poly1305.KeySize, nonceSize: chacha20poly1305.NonceSize, aead: chacha20poly1305.New}, } var SupportedKDFs = map[uint16]func() *hkdfKDF{ // RFC 9180, Section 7.2 0x0001: func() *hkdfKDF { return &hkdfKDF{crypto.SHA256} }, } func SetupSender(kemID, kdfID, aeadID uint16, pub crypto.PublicKey, info []byte) ([]byte, *Sender, error) { suiteID := SuiteID(kemID, kdfID, aeadID) kem, err := newDHKem(kemID) if err != nil { return nil, nil, err } pubRecipient, ok := pub.(*ecdh.PublicKey) if !ok { return nil, nil, errors.New("incorrect public key type") } sharedSecret, encapsulatedKey, err := kem.Encap(pubRecipient) if err != nil { return nil, nil, err } kdfInit, ok := SupportedKDFs[kdfID] if !ok { return nil, nil, errors.New("unsupported KDF id") } kdf := kdfInit() aeadInfo, ok := SupportedAEADs[aeadID] if !ok { return nil, nil, errors.New("unsupported AEAD id") } pskIDHash := kdf.LabeledExtract(suiteID, nil, "psk_id_hash", nil) infoHash := kdf.LabeledExtract(suiteID, nil, "info_hash", info) ksContext := append([]byte{0}, pskIDHash...) ksContext = append(ksContext, infoHash...) secret := kdf.LabeledExtract(suiteID, sharedSecret, "secret", nil) key := kdf.LabeledExpand(suiteID, secret, "key", ksContext, uint16(aeadInfo.keySize) /* Nk - key size for AEAD */) baseNonce := kdf.LabeledExpand(suiteID, secret, "base_nonce", ksContext, uint16(aeadInfo.nonceSize) /* Nn - nonce size for AEAD */) exporterSecret := kdf.LabeledExpand(suiteID, secret, "exp", ksContext, uint16(kdf.hash.Size()) /* Nh - hash output size of the kdf*/) aead, err := aeadInfo.aead(key) if err != nil { return nil, nil, err } return encapsulatedKey, &Sender{ kem: kem, aead: aead, sharedSecret: sharedSecret, suiteID: suiteID, key: key, baseNonce: baseNonce, exporterSecret: exporterSecret, }, nil } func (s *Sender) nextNonce() []byte { nonce := s.seqNum.bytes()[16-s.aead.NonceSize():] for i := range s.baseNonce { nonce[i] ^= s.baseNonce[i] } // Message limit is, according to the RFC, 2^95+1, which // is somewhat confusing, but we do as we're told. if s.seqNum.bitLen() >= (s.aead.NonceSize()*8)-1 { panic("message limit reached") } s.seqNum = s.seqNum.addOne() return nonce } func (s *Sender) Seal(aad, plaintext []byte) ([]byte, error) { ciphertext := s.aead.Seal(nil, s.nextNonce(), plaintext, aad) return ciphertext, nil } func SuiteID(kemID, kdfID, aeadID uint16) []byte { suiteID := make([]byte, 0, 4+2+2+2) suiteID = append(suiteID, []byte("HPKE")...) suiteID = binary.BigEndian.AppendUint16(suiteID, kemID) suiteID = binary.BigEndian.AppendUint16(suiteID, kdfID) suiteID = binary.BigEndian.AppendUint16(suiteID, aeadID) return suiteID } func ParseHPKEPublicKey(kemID uint16, bytes []byte) (*ecdh.PublicKey, error) { kemInfo, ok := SupportedKEMs[kemID] if !ok { return nil, errors.New("unsupported KEM id") } return kemInfo.curve.NewPublicKey(bytes) } type uint128 struct { hi, lo uint64 } func (u uint128) addOne() uint128 { lo, carry := bits.Add64(u.lo, 1, 0) return uint128{u.hi + carry, lo} } func (u uint128) bitLen() int { return bits.Len64(u.hi) + bits.Len64(u.lo) } func (u uint128) bytes() []byte { b := make([]byte, 16) binary.BigEndian.PutUint64(b[0:], u.hi) binary.BigEndian.PutUint64(b[8:], u.lo) return b }