negotiation

package
v4.0.2 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package negotiation finalizes ClientHello offers and validates handshake negotiation against them.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildClientHelloRetry

func BuildClientHelloRetry(initial ClientHelloSnapshot, request RetryRequest, freshShare *extension13.KeyShareEntry) (*handshake.MessageClientHello, error)

BuildClientHelloRetry clones the exact finalized ClientHello1 and applies only the changes authorized by request. The caller may run its hook on the result, but must validate the hook result with ValidateClientHelloRetry.

https://www.rfc-editor.org/rfc/rfc9846#section-4.2.2 https://www.rfc-editor.org/rfc/rfc9846#section-4.2.4

func ClientHelloFromSnapshot

func ClientHelloFromSnapshot(snapshot ClientHelloSnapshot) (*handshake.MessageClientHello, error)

ClientHelloFromSnapshot returns a detached decoded copy of snapshot.

func ConnectionIDOffer

func ConnectionIDOffer(snapshot ClientHelloSnapshot) ([]byte, bool)

ConnectionIDOffer returns the offered connection ID and its presence.

func FinalizeServerHello

FinalizeServerHello clones and validates a ServerHello before and after its hook.

func ValidateClientHelloRetry

func ValidateClientHelloRetry(
	initial, retry ClientHelloSnapshot,
	request RetryRequest,
) error

ValidateClientHelloRetry requires ClientHello2 to equal ClientHello1 except for the changes authorized by a validated HelloRetryRequest, removal of early_data, and padding changes. Extensions are compared regardless of their order.

https://www.rfc-editor.org/rfc/rfc9846#section-4.2.2

func ValidateHelloVerifyRequestResponse

func ValidateHelloVerifyRequestResponse(initial, retry ClientHelloSnapshot, cookie []byte) error

ValidateHelloVerifyRequestResponse validates the RFC 6347 fields that must remain stable across HelloVerifyRequest. DTLS 1.2 does not require byte-for-byte extension equality, but the existing CID and SRTP retry validation still apply.

func ValidateResponseExtensions

func ValidateResponseExtensions(offer ClientHelloSnapshot, values []extension.Value, allowed func(extension.Type) bool) error

func ValidateSRTPRetry

func ValidateSRTPRetry(initial, retry ClientHelloSnapshot) error

ValidateSRTPRetry requires CH2 to preserve CH1's exact use_srtp payload.

func ValidateServerHello12Context

func ValidateServerHello12Context(serverHello *handshake.MessageServerHello) error

ValidateServerHello12Context rejects responses that the wire codec classified as HelloRetryRequest or DTLS 1.3 ServerHello.

func ValidateServerHelloAfterRetry

func ValidateServerHelloAfterRetry(request RetryRequest, serverHello *handshake.MessageServerHello) error

ValidateServerHelloAfterRetry binds the final ServerHello to the cipher suite and, when using (EC)DHE, selected group from the HelloRetryRequest.

func ValidateServerHelloResponse

func ValidateServerHelloResponse(
	offer ClientHelloSnapshot,
	serverHello *handshake.MessageServerHello,
) error

ValidateServerHelloResponse validates response types against the exact final ClientHello offer.

DTLS 1.2: "An extension type MUST NOT appear in the ServerHello unless the same extension type appeared in the corresponding ClientHello."

https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.4

DTLS 1.3: "Implementations MUST NOT send extension responses (i.e., in the ServerHello, EncryptedExtensions, HelloRetryRequest, and Certificate messages) if the remote endpoint did not send the corresponding extension requests" https://www.rfc-editor.org/info/rfc9846/#section-4.3

DTLS 1.2 exception: "sending a "renegotiation_info" extension in response to a ClientHello containing only the SCSV is an explicit exception"

https://www.rfc-editor.org/rfc/rfc5746#section-3.6

Types

type ClientHelloSnapshot

type ClientHelloSnapshot struct {
	// contains filtered or unexported fields
}

ClientHelloSnapshot is an immutable copy of a validated ClientHello body.

func FinalizeClientHello

FinalizeClientHello clones and validates a ClientHello before and after the hook.

func (ClientHelloSnapshot) Extension

func (s ClientHelloSnapshot) Extension(typ extension.Type) (extension.Raw, bool)

Extension returns a copy of the extension with typ.

func (ClientHelloSnapshot) Offered

func (s ClientHelloSnapshot) Offered(typ extension.Type) bool

Offered reports whether the ClientHello contained typ.

func (ClientHelloSnapshot) Valid

func (s ClientHelloSnapshot) Valid() bool

Valid reports whether the snapshot contains a ClientHello.

type ClientHelloSnapshots

type ClientHelloSnapshots struct {
	// contains filtered or unexported fields
}

ClientHelloSnapshots retains the initial and most recent offers. Its snapshots are immutable.

func (ClientHelloSnapshots) Current

Current returns the most recent offer.

func (ClientHelloSnapshots) Initial

Initial returns the initial offer.

func (*ClientHelloSnapshots) Record

func (s *ClientHelloSnapshots) Record(snapshot ClientHelloSnapshot) error

Record retains snapshot as the current offer, rejecting a changed CID on retry.

func (*ClientHelloSnapshots) RecordWire

func (s *ClientHelloSnapshots) RecordWire(rawHandshake []byte) error

RecordWire retains the exact ClientHello body from an unfragmented DTLS handshake.

func (*ClientHelloSnapshots) Reset

func (s *ClientHelloSnapshots) Reset()

Reset removes all retained offers.

type ConnectionID

type ConnectionID struct {
	ClientCID, ServerCID   []byte
	ReturnRoutabilityCheck bool
}

ConnectionID is the session-wide CID negotiation decision.

func DecideConnectionID

func DecideConnectionID(offer ClientHelloSnapshot, responses []extension.Value) *ConnectionID

DecideConnectionID derives a CID decision from an offer and final response.

type RetryRequest

type RetryRequest struct {
	CipherSuiteID    uint16
	SelectedGroup    elliptic.Curve
	Cookie           []byte
	HasSelectedGroup bool
	HasCookie        bool
	// contains filtered or unexported fields
}

RetryRequest is the set of changes authorized by one validated HelloRetryRequest.

func ValidateHelloRetryRequest

func ValidateHelloRetryRequest(
	initial ClientHelloSnapshot,
	hrr *handshake.MessageServerHello,
) (RetryRequest, error)

ValidateHelloRetryRequest validates the parts of an HRR that constrain ClientHello2 and the final ServerHello.

https://www.rfc-editor.org/rfc/rfc9846#section-4.2.4

type SRTPDecision

type SRTPDecision struct {
	ProtectionProfile       extension.SRTPProtectionProfile
	MasterKeyIdentifier     []byte
	PeerMasterKeyIdentifier []byte
}

SRTPDecision is the validated use_srtp result for one handshake.

func NegotiateSRTP

func NegotiateSRTP(snapshot ClientHelloSnapshot, localProfiles []extension.SRTPProtectionProfile, acceptedMKI []byte) (SRTPDecision, error)

NegotiateSRTP selects the server-preferred profile from the exact offer.

func ValidateSRTPSelection

func ValidateSRTPSelection(snapshot ClientHelloSnapshot, responses []extension.Value, localProfiles []extension.SRTPProtectionProfile) (SRTPDecision, error)

ValidateSRTPSelection validates one server selection against the exact offer.

Jump to

Keyboard shortcuts

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