handshake

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: 20 Imported by: 0

Documentation

Overview

Package handshake provides the DTLS wire protocol for handshakes

Index

Constants

View Source
const (
	TypeHelloRequest        = handshakewire.TypeHelloRequest
	TypeClientHello         = handshakewire.TypeClientHello
	TypeServerHello         = handshakewire.TypeServerHello
	TypeHelloVerifyRequest  = handshakewire.TypeHelloVerifyRequest
	TypeNewSessionTicket    = handshakewire.TypeNewSessionTicket
	TypeEncryptedExtensions = handshakewire.TypeEncryptedExtensions
	TypeRequestConnectionID = handshakewire.TypeRequestConnectionID
	TypeNewConnectionID     = handshakewire.TypeNewConnectionID
	TypeCertificate         = handshakewire.TypeCertificate
	TypeServerKeyExchange   = handshakewire.TypeServerKeyExchange
	TypeCertificateRequest  = handshakewire.TypeCertificateRequest
	TypeServerHelloDone     = handshakewire.TypeServerHelloDone
	TypeCertificateVerify   = handshakewire.TypeCertificateVerify
	TypeClientKeyExchange   = handshakewire.TypeClientKeyExchange
	TypeFinished            = handshakewire.TypeFinished
	TypeKeyUpdate           = handshakewire.TypeKeyUpdate
	// TypeMessageHash is a synthetic TLS 1.3 transcript-only handshake type.
	TypeMessageHash = handshakewire.TypeMessageHash
)

Types of DTLS Handshake messages we know about.

View Source
const (
	RandomBytesLength = 28
	RandomLength      = RandomBytesLength + 4
)

Consts for Random in Handshake.

View Source
const HeaderLength = 12

HeaderLength msg_len for Handshake messages assumes an extra 12 bytes for sequence, fragment and version information vs TLS.

Variables

This section is empty.

Functions

func HelloRetryRequestRandom

func HelloRetryRequestRandom() []byte

HelloRetryRequestRandom is set as the Random value of a ServerHello to signal that the message is actually a HelloRetryRequest. See RFC 8446 Section 4.1.3.

Types

type ConnectionIDUsage

type ConnectionIDUsage uint8

ConnectionIDUsage indicates whether new CIDs should be used immediately or retained for future use.

const (
	ConnectionIDImmediate ConnectionIDUsage = iota
	ConnectionIDSpare
)

ConnectionIDUsage values.

type Handshake

type Handshake struct {
	Header  Header
	Message Message

	KeyExchangeAlgorithm ciphersuite.KeyExchangeAlgorithm

	// Version selects version-dependent message formats during Unmarshal.
	// Zero uses DTLS 1.3.
	Version protocol.Version
}

Handshake protocol is responsible for selecting a cipher spec and generating a master secret, which together comprise the primary cryptographic parameters associated with a secure session. The handshake protocol can also optionally authenticate parties who have certificates signed by a trusted certificate authority. https://tools.ietf.org/html/rfc5246#section-7.3

func (Handshake) ContentType

func (h Handshake) ContentType() protocol.ContentType

ContentType returns what kind of content this message is carying.

func (*Handshake) Marshal

func (h *Handshake) Marshal() ([]byte, error)

Marshal encodes a handshake into a binary message.

func (*Handshake) MarshalSize

func (h *Handshake) MarshalSize() int

MarshalSize returns the minimal buffer size required for MarshalTo.

func (*Handshake) MarshalTo

func (h *Handshake) MarshalTo(out []byte) (int, error)

MarshalTo encodes a handshake into a binary message into a pre-allocated buffer.

func (*Handshake) Unmarshal

func (h *Handshake) Unmarshal(data []byte) error

Unmarshal decodes a handshake from a binary message.

type Header struct {
	Type            Type
	Length          uint32 // uint24 in spec
	MessageSequence uint16
	FragmentOffset  uint32 // uint24 in spec
	FragmentLength  uint32 // uint24 in spec
}

Header is the static first 12 bytes of each RecordLayer of type Handshake. These fields allow us to support message loss, reordering, and message fragmentation,

https://tools.ietf.org/html/rfc6347#section-4.2.2

func (*Header) Marshal

func (h *Header) Marshal() ([]byte, error)

Marshal encodes the Header.

func (*Header) MarshalTo

func (h *Header) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Header using a pre-allocated buffer.

func (*Header) Unmarshal

func (h *Header) Unmarshal(data []byte) error

Unmarshal populates the header from encoded data.

type KeyUpdateRequest

type KeyUpdateRequest uint8

KeyUpdateRequest indicates whether the recipient should update its sending traffic keys as well.

const (
	KeyUpdateNotRequested KeyUpdateRequest = iota
	KeyUpdateRequested
)

KeyUpdateRequest values.

type Message

type Message interface {
	Marshal() ([]byte, error)
	MarshalTo([]byte) (int, error)
	MarshalSize() int
	Unmarshal(data []byte) error
	Type() Type
}

Message is the body of a Handshake datagram.

type MessageCertificateVerify

type MessageCertificateVerify struct {
	HashAlgorithm      hash.Algorithm
	SignatureAlgorithm signature.Algorithm
	Signature          []byte
}

MessageCertificateVerify provide explicit verification of a client certificate.

https://tools.ietf.org/html/rfc5246#section-7.4.8

func (*MessageCertificateVerify) Marshal

func (m *MessageCertificateVerify) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (MessageCertificateVerify) MarshalSize

func (m MessageCertificateVerify) MarshalSize() int

MarshalSize returns the minimal required size for Marshalnto.

func (*MessageCertificateVerify) MarshalTo

func (m *MessageCertificateVerify) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageCertificateVerify) Type

func (m MessageCertificateVerify) Type() Type

Type returns the Handshake Type.

func (*MessageCertificateVerify) Unmarshal

func (m *MessageCertificateVerify) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageClientHello

type MessageClientHello struct {
	Version protocol.Version
	Random  Random
	Cookie  []byte

	SessionID []byte

	CipherSuiteIDs     []uint16
	CompressionMethods []*protocol.CompressionMethod
	Extensions         []extension.Value
}

MessageClientHello is for when a client first connects to a server it is required to send the client hello as its first message. The client can also send a client hello in response to a hello request or on its own initiative in order to renegotiate the security parameters in an existing connection.

func (*MessageClientHello) Marshal

func (m *MessageClientHello) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageClientHello) MarshalSize

func (m *MessageClientHello) MarshalSize() int

MarshalSize returns the size needed for MarshalTo.

func (*MessageClientHello) MarshalTo

func (m *MessageClientHello) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageClientHello) Type

func (m MessageClientHello) Type() Type

Type returns the Handshake Type.

func (*MessageClientHello) Unmarshal

func (m *MessageClientHello) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageClientKeyExchange

type MessageClientKeyExchange struct {
	IdentityHint []byte
	PublicKey    []byte

	// for unmarshaling
	KeyExchangeAlgorithm ciphersuite.KeyExchangeAlgorithm
}

MessageClientKeyExchange is a DTLS Handshake Message With this message, the premaster secret is set, either by direct transmission of the RSA-encrypted secret or by the transmission of Diffie-Hellman parameters that will allow each side to agree upon the same premaster secret.

https://tools.ietf.org/html/rfc5246#section-7.4.7

func (*MessageClientKeyExchange) Marshal

func (m *MessageClientKeyExchange) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageClientKeyExchange) MarshalSize

func (m *MessageClientKeyExchange) MarshalSize() int

MarshalSize returns the size required for MarshalTo.

func (*MessageClientKeyExchange) MarshalTo

func (m *MessageClientKeyExchange) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageClientKeyExchange) Type

func (m MessageClientKeyExchange) Type() Type

Type returns the Handshake Type.

func (*MessageClientKeyExchange) Unmarshal

func (m *MessageClientKeyExchange) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageEncryptedExtensions

type MessageEncryptedExtensions struct {
	Extensions []extension.Value
}

MessageEncryptedExtensions message contains extensions that can be protected, i.e., any which are not needed to establish the cryptographic context

https://datatracker.ietf.org/doc/html/rfc8446#section-4.3.1

func (*MessageEncryptedExtensions) Marshal

func (m *MessageEncryptedExtensions) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageEncryptedExtensions) MarshalSize

func (m *MessageEncryptedExtensions) MarshalSize() int

MarshalSize returns the minimal size required for MarshalTo.

func (*MessageEncryptedExtensions) MarshalTo

func (m *MessageEncryptedExtensions) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageEncryptedExtensions) Type

Type returns the Handshake Type.

func (*MessageEncryptedExtensions) Unmarshal

func (m *MessageEncryptedExtensions) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageFinished

type MessageFinished struct {
	VerifyData []byte
}

MessageFinished is a DTLS Handshake Message this message is the first one protected with the just negotiated algorithms, keys, and secrets. Recipients of Finished messages MUST verify that the contents are correct.

https://tools.ietf.org/html/rfc5246#section-7.4.9

func (*MessageFinished) Marshal

func (m *MessageFinished) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageFinished) MarshalSize

func (m *MessageFinished) MarshalSize() int

MarshalSize returns the size required for MarshalTo.

func (*MessageFinished) MarshalTo

func (m *MessageFinished) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageFinished) Type

func (m MessageFinished) Type() Type

Type returns the Handshake Type.

func (*MessageFinished) Unmarshal

func (m *MessageFinished) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageHelloVerifyRequest

type MessageHelloVerifyRequest struct {
	Version protocol.Version
	Cookie  []byte
}

MessageHelloVerifyRequest is as follows:

struct {
  ProtocolVersion server_version;
  opaque cookie<0..2^8-1>;
} HelloVerifyRequest;

The HelloVerifyRequest message type is hello_verify_request(3).

When the client sends its ClientHello message to the server, the server
MAY respond with a HelloVerifyRequest message.  This message contains
a stateless cookie generated using the technique of [PHOTURIS].  The
client MUST retransmit the ClientHello with the cookie added.

https://tools.ietf.org/html/rfc6347#section-4.2.1

func (*MessageHelloVerifyRequest) Marshal

func (m *MessageHelloVerifyRequest) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageHelloVerifyRequest) MarshalSize

func (m *MessageHelloVerifyRequest) MarshalSize() int

MarshalSize returns the size required for MarshalTo.

func (*MessageHelloVerifyRequest) MarshalTo

func (m *MessageHelloVerifyRequest) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageHelloVerifyRequest) Type

Type returns the Handshake Type.

func (*MessageHelloVerifyRequest) Unmarshal

func (m *MessageHelloVerifyRequest) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageKeyUpdate

type MessageKeyUpdate struct {
	RequestUpdate KeyUpdateRequest
}

MessageKeyUpdate requests an update of DTLS 1.3 application traffic keys.

https://datatracker.ietf.org/doc/html/rfc8446#section-4.6.3

func (*MessageKeyUpdate) Marshal

func (m *MessageKeyUpdate) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageKeyUpdate) MarshalSize

func (m *MessageKeyUpdate) MarshalSize() int

MarshalSize returns the minimal size required for MarshalTo.

func (*MessageKeyUpdate) MarshalTo

func (m *MessageKeyUpdate) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageKeyUpdate) Type

func (m MessageKeyUpdate) Type() Type

Type returns the Handshake Type.

func (*MessageKeyUpdate) Unmarshal

func (m *MessageKeyUpdate) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageNewConnectionID

type MessageNewConnectionID struct {
	CIDs  [][]byte
	Usage ConnectionIDUsage
}

MessageNewConnectionID supplies CIDs for a peer to use when sending records.

https://datatracker.ietf.org/doc/html/rfc9147#section-9

func (*MessageNewConnectionID) Marshal

func (m *MessageNewConnectionID) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageNewConnectionID) MarshalSize

func (m *MessageNewConnectionID) MarshalSize() int

MarshalSize returns the minimal size required for MarshalTo.

func (*MessageNewConnectionID) MarshalTo

func (m *MessageNewConnectionID) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageNewConnectionID) Type

func (m MessageNewConnectionID) Type() Type

Type returns the Handshake Type.

func (*MessageNewConnectionID) Unmarshal

func (m *MessageNewConnectionID) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageNewSessionTicket

type MessageNewSessionTicket struct {
	TicketLifetime uint32
	TicketAgeAdd   uint32
	TicketNonce    []byte
	Ticket         []byte
	Extensions     []extension.Value
}

MessageNewSessionTicket establishes a PSK that a client can use to resume a DTLS 1.3 connection.

https://datatracker.ietf.org/doc/html/rfc8446#section-4.6.1

func (*MessageNewSessionTicket) Marshal

func (m *MessageNewSessionTicket) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageNewSessionTicket) MarshalSize

func (m *MessageNewSessionTicket) MarshalSize() int

MarshalSize returns the minimal size required for MarshalTo.

func (*MessageNewSessionTicket) MarshalTo

func (m *MessageNewSessionTicket) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake.

func (MessageNewSessionTicket) Type

func (m MessageNewSessionTicket) Type() Type

Type returns the Handshake Type.

func (*MessageNewSessionTicket) Unmarshal

func (m *MessageNewSessionTicket) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageRequestConnectionID

type MessageRequestConnectionID struct {
	NumCIDs uint8
}

MessageRequestConnectionID requests spare CIDs from a peer.

https://datatracker.ietf.org/doc/html/rfc9147#section-9

func (*MessageRequestConnectionID) Marshal

func (m *MessageRequestConnectionID) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageRequestConnectionID) MarshalSize

func (m *MessageRequestConnectionID) MarshalSize() int

MarshalSize returns the minimal size required for MarshalTo.

func (*MessageRequestConnectionID) MarshalTo

func (m *MessageRequestConnectionID) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageRequestConnectionID) Type

Type returns the Handshake Type.

func (*MessageRequestConnectionID) Unmarshal

func (m *MessageRequestConnectionID) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageServerHello

type MessageServerHello struct {
	Version protocol.Version
	Random  Random

	SessionID []byte

	CipherSuiteID     *uint16
	CompressionMethod *protocol.CompressionMethod
	Extensions        []extension.Value
}

MessageServerHello is sent in response to a ClientHello message when it was able to find an acceptable set of algorithms. If it cannot find such a match, it will respond with a handshake failure alert.

https://tools.ietf.org/html/rfc5246#section-7.4.1.3

func (*MessageServerHello) Marshal

func (m *MessageServerHello) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageServerHello) MarshalSize

func (m *MessageServerHello) MarshalSize() int

MarshalSize returns the size required by MarshalTo.

func (*MessageServerHello) MarshalTo

func (m *MessageServerHello) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageServerHello) Type

func (m MessageServerHello) Type() Type

Type returns the Handshake Type.

func (*MessageServerHello) Unmarshal

func (m *MessageServerHello) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type MessageServerHelloDone

type MessageServerHelloDone struct{}

MessageServerHelloDone is final non-encrypted message from server this communicates server has sent all its handshake messages and next should be MessageFinished.

func (*MessageServerHelloDone) Marshal

func (m *MessageServerHelloDone) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageServerHelloDone) MarshalSize

func (m *MessageServerHelloDone) MarshalSize() int

MarshalSize returns the size for MarshalTo.

func (*MessageServerHelloDone) MarshalTo

func (m *MessageServerHelloDone) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake.

func (MessageServerHelloDone) Type

func (m MessageServerHelloDone) Type() Type

Type returns the Handshake Type.

func (*MessageServerHelloDone) Unmarshal

func (m *MessageServerHelloDone) Unmarshal([]byte) error

Unmarshal populates the message from encoded data.

type MessageServerKeyExchange

type MessageServerKeyExchange struct {
	IdentityHint []byte

	EllipticCurveType  elliptic.CurveType
	NamedCurve         elliptic.Curve
	PublicKey          []byte
	HashAlgorithm      hash.Algorithm
	SignatureAlgorithm signature.Algorithm
	Signature          []byte

	// for unmarshaling
	KeyExchangeAlgorithm ciphersuite.KeyExchangeAlgorithm
}

MessageServerKeyExchange supports ECDH and PSK.

func (*MessageServerKeyExchange) Marshal

func (m *MessageServerKeyExchange) Marshal() ([]byte, error)

Marshal encodes the Handshake.

func (*MessageServerKeyExchange) MarshalSize

func (m *MessageServerKeyExchange) MarshalSize() int

MarshalSize returns the size required for MarshalTo.

func (*MessageServerKeyExchange) MarshalTo

func (m *MessageServerKeyExchange) MarshalTo(out []byte) (int, error)

MarshalTo encodes the Handshake into a pre-allocated buffer.

func (MessageServerKeyExchange) Type

func (m MessageServerKeyExchange) Type() Type

Type returns the Handshake Type.

func (*MessageServerKeyExchange) Unmarshal

func (m *MessageServerKeyExchange) Unmarshal(data []byte) error

Unmarshal populates the message from encoded data.

type Random

type Random struct {
	GMTUnixTime time.Time
	RandomBytes [RandomBytesLength]byte
}

Random value that is used in ClientHello and ServerHello

https://tools.ietf.org/html/rfc4346#section-7.4.1.2

func (*Random) MarshalFixed

func (r *Random) MarshalFixed() [RandomLength]byte

MarshalFixed encodes the Handshake.

func (*Random) Populate

func (r *Random) Populate() error

Populate fills the handshakeRandom with random values may be called multiple times.

func (*Random) UnmarshalFixed

func (r *Random) UnmarshalFixed(data [RandomLength]byte)

UnmarshalFixed populates the message from encoded data.

type Type

type Type = handshakewire.Type

Type is the unique identifier for each handshake message. https://tools.ietf.org/html/rfc5246#section-7.4

Directories

Path Synopsis
Package dtls12 implements certificate message wire formats for DTLS 1.2.
Package dtls12 implements certificate message wire formats for DTLS 1.2.
Package dtls13 implements certificate message wire formats for DTLS 1.3.
Package dtls13 implements certificate message wire formats for DTLS 1.3.

Jump to

Keyboard shortcuts

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