handshake

package
v3.1.2 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2026 License: MIT Imports: 14 Imported by: 13

Documentation

Overview

Package handshake provides the DTLS wire protocol for handshakes

Index

Constants

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

This section is empty.

Types

type CertificateEntry13 added in v3.1.0 

type CertificateEntry13 struct {
	// CertificateData contains the DER-encoded X.509 certificate.
	// Can be empty for certain contexts (e.g., RawPublicKey mode).
	CertificateData []byte

	// Extensions contains per-certificate extensions.
	// Examples: OCSP status, SignedCertificateTimestamp, etc.
	Extensions []extension.Extension
}

CertificateEntry13 represents a single certificate entry in the DTLS 1.3 Certificate message. Each entry contains certificate data and optional per-certificate extensions.

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

type Handshake 

type Handshake struct {
	Header  Header
	Message Message

	KeyExchangeAlgorithm types.KeyExchangeAlgorithm
}

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) 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) Unmarshal 

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

Unmarshal populates the header from encoded data.

type Message 

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

Message is the body of a Handshake datagram.

type MessageCertificate 

type MessageCertificate struct {
	Certificate [][]byte
}

MessageCertificate is a DTLS Handshake Message it can contain either a Client or Server Certificate

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

func (*MessageCertificate) Marshal 

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

Marshal encodes the Handshake.

func (MessageCertificate) Type 

func (m MessageCertificate) Type() Type

Type returns the Handshake Type.

func (*MessageCertificate) Unmarshal 

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

Unmarshal populates the message from encoded data.

type MessageCertificate13 added in v3.1.0 

type MessageCertificate13 struct {
	// CertificateRequestContext is an opaque value that binds this certificate
	// to a specific CertificateRequest (for client certificates) or is empty
	// for server certificates.
	CertificateRequestContext []byte

	// CertificateList contains the certificate chain with each entry having
	// optional per-certificate extensions.
	CertificateList []CertificateEntry13
}

MessageCertificate13 represents the Certificate handshake message for DTLS 1.3. This message is used to transport the certificate chain and associated extensions.

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

func (*MessageCertificate13) Marshal added in v3.1.0 

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

Marshal encodes the MessageCertificate13 into its wire format.

Wire format: 

[1 byte]  certificate_request_context length
[0-255]   certificate_request_context data
[3 bytes] certificate_list length
For each certificate:
  [3 bytes]  cert_data length
  [variable] cert_data (DER certificate)
  [2 bytes]  extensions length (from extension.Marshal)
  [variable] extensions data

func (MessageCertificate13) Type added in v3.1.0 

func (m MessageCertificate13) Type() Type

Type returns the handshake message type.

func (*MessageCertificate13) Unmarshal added in v3.1.0 

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

Unmarshal decodes the MessageCertificate13 from its wire format.

type MessageCertificateRequest 

type MessageCertificateRequest struct {
	CertificateTypes            []clientcertificate.Type
	SignatureHashAlgorithms     []signaturehash.Algorithm
	CertificateAuthoritiesNames [][]byte
}

MessageCertificateRequest is so a non-anonymous server can optionally request a certificate from the client, if appropriate for the selected cipher suite. This message, if sent, will immediately follow the ServerKeyExchange message (if it is sent; otherwise, this message follows the server's Certificate message).

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

func (*MessageCertificateRequest) Marshal 

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

Marshal encodes the Handshake.

func (MessageCertificateRequest) Type 

func (m MessageCertificateRequest) Type() Type

Type returns the Handshake Type.

func (*MessageCertificateRequest) Unmarshal 

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

Unmarshal populates the message from encoded data.

type MessageCertificateRequest13 added in v3.1.0 

type MessageCertificateRequest13 struct {
	// CertificateRequestContext is an opaque value that the server creates
	// to bind the client's certificate to the handshake context.
	CertificateRequestContext []byte

	// Extensions contains the list of extensions.
	// The signature_algorithms extension is REQUIRED per RFC 8446.
	Extensions []extension.Extension
}

MessageCertificateRequest13 represents the CertificateRequest handshake message for DTLS 1.3. This message is used by the server to request a certificate from the client.

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

func (*MessageCertificateRequest13) Marshal added in v3.1.0 

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

Marshal encodes the MessageCertificateRequest13 into its wire format.

Wire format: 

[1 byte]  certificate_request_context length
[0-255]   certificate_request_context data
[2 bytes] extensions length (from extension.Marshal)
[variable] extensions data

func (MessageCertificateRequest13) Type added in v3.1.0 

func (m MessageCertificateRequest13) Type() Type

Type returns the handshake message type.

func (*MessageCertificateRequest13) Unmarshal added in v3.1.0 

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

Unmarshal decodes the MessageCertificateRequest13 from its wire format.

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) 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.Extension
}

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) 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 types.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() (out []byte, err error)

Marshal encodes the Handshake.

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 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) 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) Type 

func (m MessageHelloVerifyRequest) Type() Type

Type returns the Handshake Type.

func (*MessageHelloVerifyRequest) Unmarshal 

func (m *MessageHelloVerifyRequest) 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.Extension
}

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) 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) 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 types.KeyExchangeAlgorithm
}

MessageServerKeyExchange supports ECDH and PSK.

func (*MessageServerKeyExchange) Marshal 

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

Marshal encodes the Handshake.

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 uint8

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

const (
	TypeHelloRequest       Type = 0
	TypeClientHello        Type = 1
	TypeServerHello        Type = 2
	TypeHelloVerifyRequest Type = 3
	TypeCertificate        Type = 11
	TypeServerKeyExchange  Type = 12
	TypeCertificateRequest Type = 13
	TypeServerHelloDone    Type = 14
	TypeCertificateVerify  Type = 15
	TypeClientKeyExchange  Type = 16
	TypeFinished           Type = 20
)

Types of DTLS Handshake messages we know about.

func (Type) String 

func (t Type) String() string

String returns the string representation of this type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.