ech

package
v4.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package ech implements wire and cryptographic helpers for https://www.rfc-editor.org/rfc/rfc9849.

Index

Constants

View Source
const Version uint16 = 0xfe0d

Variables

View Source
var (
	ErrInvalid     = errors.New("malformed ECH encoding")
	ErrUnsupported = errors.New("unsupported ECH configuration")
	ErrToolchain   = errors.New("ECH requires Go 1.26 or later")
)

Functions

func AcceptanceConfirmation

func AcceptanceConfirmation(hashFunc func() hash.Hash, inner, serverHello []byte) ([]byte, error)

AcceptanceConfirmation computes the normal ServerHello confirmation, with the final eight random bytes zeroed. Inputs are headerless DTLS bodies; https://www.rfc-editor.org/rfc/rfc9849#section-7.2 https://www.rfc-editor.org/rfc/rfc9147#section-5.9

func Available

func Available() bool

func DecodeInnerClientHello

func DecodeInnerClientHello(encoded, outer []byte) ([]byte, error)

DecodeInnerClientHello validates padding and expands outer references in linear time, preserving their order and rejecting duplicates and forbidden references.

func EncodeInnerClientHello

func EncodeInnerClientHello(inner []byte, maximumNameLength uint8, nameLength int) ([]byte, error)

EncodeInnerClientHello clears the session ID and adds RFC 9849 section 6.1.3 padding. Compression is optional; callers may supply ECHOuterExtensions explicitly. nameLength is -1 when no server_name is present.

func OuterAAD

func OuterAAD(outer []byte) ([]byte, error)

OuterAAD replaces only the ciphertext payload with equal-length zeros. The input is a ClientHello body, without record or handshake headers.

func PickConfig

func PickConfig(configs []Config) (*Config, CipherSuite, error)

PickConfig selects the first usable configuration and its first supported cipher suite, following the server's advertised preference. Invalid public keys and unsupported mandatory extensions are skipped.

func RetryConfirmation

func RetryConfirmation(hashFunc func() hash.Hash, inner, zeroedHRR []byte) ([]byte, error)

RetryConfirmation computes HRR confirmation with its ECH extension zeroed.

Types

type CipherSuite

type CipherSuite struct{ KDFID, AEADID uint16 }

CipherSuite identifies an HPKE symmetric cipher suite.

type ClientContext

type ClientContext struct {
	Config                          Config
	Suite                           CipherSuite
	Sender                          Sender
	Inner, Outer                    []byte
	Accepted                        bool
	Rejected                        bool   // Selects the outer handshake.
	RetryConfigList                 []byte // Published only after verifying the server flight.
	InitialInner, HelloRetryRequest []byte
	// contains filtered or unexported fields
}

ClientContext retains the initial inner and outer bodies and HPKE state.

func NewClientHello

func NewClientHello(configList, body []byte) (*ClientContext, error)

NewClientHello constructs an initial ECH offer.

func PrepareClientHello

func PrepareClientHello(configList, body []byte) (*ClientContext, error)

PrepareClientHello constructs the inner hello before PSK binders are computed.

func (*ClientContext) AcceptRetry

func (c *ClientContext) AcceptRetry(hashFunc func() hash.Hash, body []byte) error

AcceptRetry verifies HRR confirmation over its exact wire encoding. https://www.rfc-editor.org/rfc/rfc9849#section-6.1.4

func (*ClientContext) Confirmation

func (c *ClientContext) Confirmation(hashFunc func() hash.Hash, body []byte) ([]byte, error)

Confirmation includes both inner ClientHellos when the server requested a retry.

func (*ClientContext) RetryClientHello

func (c *ClientContext) RetryClientHello(inner []byte) error

RetryClientHello reuses the sender and sends an empty enc in ClientHello2. The caller validates the inner against the authenticated retry request first. https://www.rfc-editor.org/rfc/rfc9849#section-6.1.2

func (*ClientContext) SealClientHello

func (c *ClientContext) SealClientHello(inner []byte) error

SealClientHello encrypts the finalized initial inner hello, including binders.

type Config

type Config struct {
	Raw                  []byte
	Version              uint16
	Length               uint16
	ConfigID             uint8
	KemID                uint16
	PublicKey            []byte
	SymmetricCipherSuite []CipherSuite
	MaxNameLength        uint8
	PublicName           string
	Extensions           []extension.Raw
}

Config retains the original encoding, which is authenticated by HPKE.

func ParseConfig

func ParseConfig(data []byte) (skip bool, config Config, err error)

ParseConfig parses exactly one ECHConfig, skipping unknown versions. Like crypto/tls, it leaves key, suite, and name usability to selection.

func ParseConfigList

func ParseConfigList(data []byte) ([]Config, error)

ParseConfigList validates framing and skips unknown configuration versions, preserving the server's preference order.

func (Config) Usable

func (config Config) Usable() bool

Usable checks public-name syntax and rejects unsupported mandatory configuration extensions.

type Key

type Key struct {
	Config, PrivateKey []byte
	SendAsRetry        bool
}

Key associates a serialized ECHConfig with its HPKE private key.

type Recipient

type Recipient interface {
	Open(aad, ciphertext []byte) ([]byte, error)
	Export(string, int) ([]byte, error)
}

func NewRecipient

func NewRecipient(config Config, suite CipherSuite, privateKey, enc []byte) (Recipient, error)

type RejectionError

type RejectionError struct{ RetryConfigList []byte }

RejectionError reports authenticated ECH rejection. RetryConfigList may be used on a new connection.

func (*RejectionError) Error

func (*RejectionError) Error() string

type Sender

type Sender interface {
	Seal(aad, plaintext []byte) ([]byte, error)
	Export(string, int) ([]byte, error)
}

Sender and Recipient retain HPKE sequence state across ClientHellos.

func NewSender

func NewSender(config Config, s CipherSuite) ([]byte, Sender, error)

type ServerContext

type ServerContext struct {
	Inner             []byte
	Recipient         Recipient
	ConfigID          uint8
	Suite             CipherSuite
	InitialInner      []byte
	HelloRetryRequest []byte
	// contains filtered or unexported fields
}

ServerContext retains the accepted logical hello and receiving HPKE context. Its zero value means ECH was not accepted.

func ProcessClientHello

func ProcessClientHello(outer []byte, keys []Key) (ServerContext, error)

ProcessClientHello follows crypto/tls trial decryption. A zero context means ECH was not accepted. https://www.rfc-editor.org/rfc/rfc9849#section-7.1

func (*ServerContext) Confirmation

func (c *ServerContext) Confirmation(hashFunc func() hash.Hash, serverHello []byte) ([]byte, error)

Confirmation includes the synthetic message_hash and HRR after a retry.

func (*ServerContext) ProcessRetry

func (c *ServerContext) ProcessRetry(outer []byte) ([]byte, error)

ProcessRetry reuses the receiving context for ClientHello2. Exact duplicates return the cached plaintext without advancing the HPKE sequence number. https://www.rfc-editor.org/rfc/rfc9849#section-7.1.1

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL