package handshake

import "github.com/pion/dtls/v3/pkg/protocol/handshake"

Package handshake provides the DTLS wire protocol for handshakes

Index

Constants 

const (
	RandomBytesLength = 28
	RandomLength      = RandomBytesLength + 4
)

Consts for Random in Handshake 

const HeaderLength = 12

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

Types

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

cipher_suite.go errors.go handshake.go header.go message_certificate.go message_certificate_request.go message_certificate_verify.go message_client_hello.go message_client_key_exchange.go message_finished.go message_hello_verify_request.go message_server_hello.go message_server_hello_done.go message_server_key_exchange.go random.go

Version
v3.0.4 (latest)
Published
Nov 4, 2024
Platform
linux/amd64
Imports
13 packages
Last checked
1 week ago –

Tools for package owners.