Documentation
¶
Overview ¶
Package ech implements wire and cryptographic helpers for https://www.rfc-editor.org/rfc/rfc9849.
Index ¶
- Constants
- Variables
- func AcceptanceConfirmation(hashFunc func() hash.Hash, inner, serverHello []byte) ([]byte, error)
- func Available() bool
- func DecodeInnerClientHello(encoded, outer []byte) ([]byte, error)
- func EncodeInnerClientHello(inner []byte, maximumNameLength uint8, nameLength int) ([]byte, error)
- func OuterAAD(outer []byte) ([]byte, error)
- func PickConfig(configs []Config) (*Config, CipherSuite, error)
- func RetryConfirmation(hashFunc func() hash.Hash, inner, zeroedHRR []byte) ([]byte, error)
- type CipherSuite
- type ClientContext
- type Config
- type Key
- type Recipient
- type RejectionError
- type Sender
- type ServerContext
Constants ¶
const Version uint16 = 0xfe0d
Variables ¶
Functions ¶
func AcceptanceConfirmation ¶
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 DecodeInnerClientHello ¶
DecodeInnerClientHello validates padding and expands outer references in linear time, preserving their order and rejecting duplicates and forbidden references.
func EncodeInnerClientHello ¶
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 ¶
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.
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 ¶
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 ¶
ParseConfig parses exactly one ECHConfig, skipping unknown versions. Like crypto/tls, it leaves key, suite, and name usability to selection.
func ParseConfigList ¶
ParseConfigList validates framing and skips unknown configuration versions, preserving the server's preference order.
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.
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 ¶
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