Documentation
¶
Overview ¶
Package negotiation finalizes ClientHello offers and validates handshake negotiation against them.
Index ¶
- func BuildClientHelloRetry(initial ClientHelloSnapshot, request RetryRequest, ...) (*handshake.MessageClientHello, error)
- func ClientHelloFromSnapshot(snapshot ClientHelloSnapshot) (*handshake.MessageClientHello, error)
- func ConnectionIDOffer(snapshot ClientHelloSnapshot) ([]byte, bool)
- func FinalizeServerHello(base *handshake.MessageServerHello, ...) (*handshake.MessageServerHello, error)
- func ValidateClientHelloRetry(initial, retry ClientHelloSnapshot, request RetryRequest) error
- func ValidateHelloVerifyRequestResponse(initial, retry ClientHelloSnapshot, cookie []byte) error
- func ValidateResponseExtensions(offer ClientHelloSnapshot, values []extension.Value, ...) error
- func ValidateSRTPRetry(initial, retry ClientHelloSnapshot) error
- func ValidateServerHello12Context(serverHello *handshake.MessageServerHello) error
- func ValidateServerHelloAfterRetry(request RetryRequest, serverHello *handshake.MessageServerHello) error
- func ValidateServerHelloResponse(offer ClientHelloSnapshot, serverHello *handshake.MessageServerHello) error
- type ClientHelloSnapshot
- type ClientHelloSnapshots
- func (s ClientHelloSnapshots) Current() ClientHelloSnapshot
- func (s ClientHelloSnapshots) Initial() ClientHelloSnapshot
- func (s *ClientHelloSnapshots) Record(snapshot ClientHelloSnapshot) error
- func (s *ClientHelloSnapshots) RecordWire(rawHandshake []byte) error
- func (s *ClientHelloSnapshots) Reset()
- type ConnectionID
- type RetryRequest
- type SRTPDecision
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 ¶
func FinalizeServerHello(base *handshake.MessageServerHello, hook func(handshake.MessageServerHello) handshake.Message, offer ClientHelloSnapshot) (*handshake.MessageServerHello, error)
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.
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 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"
Types ¶
type ClientHelloSnapshot ¶
type ClientHelloSnapshot struct {
// contains filtered or unexported fields
}
ClientHelloSnapshot is an immutable copy of a validated ClientHello body.
func FinalizeClientHello ¶
func FinalizeClientHello(base *handshake.MessageClientHello, hook func(handshake.MessageClientHello) handshake.Message) (*handshake.MessageClientHello, ClientHelloSnapshot, error)
FinalizeClientHello clones and validates a ClientHello before and after the hook.
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 ¶
func (s ClientHelloSnapshots) Current() ClientHelloSnapshot
Current returns the most recent offer.
func (ClientHelloSnapshots) Initial ¶
func (s ClientHelloSnapshots) Initial() ClientHelloSnapshot
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 ¶
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.
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.