dtls

README

Pion DTLS

A Go implementation of DTLS

Native DTLS 1.2 implementation in the Go programming language.

A long term goal is a professional security review, and maybe an inclusion in stdlib.

RFCs

Implemented

• RFC 6347: Datagram Transport Layer Security Version 1.2
• RFC 5705: Keying Material Exporters for Transport Layer Security (TLS)
• RFC 7627: Transport Layer Security (TLS) - Session Hash and Extended Master Secret Extension
• RFC 7301: Transport Layer Security (TLS) - Application-Layer Protocol Negotiation Extension

Goals/Progress

This will only be targeting DTLS 1.2, and the most modern/common cipher suites. We would love contributions that fall under the 'Planned Features' and any bug fixes!

Current features

• DTLS 1.2 Client/Server
• Key Exchange via ECDHE(curve25519, nistp256, nistp384) and PSK
• Packet loss and re-ordering is handled during handshaking
• Key export (RFC 5705)
• Serialization and Resumption of sessions
• Extended Master Secret extension (RFC 7627)
• ALPN extension (RFC 7301)

Supported ciphers

ECDHE

• TLS_ECDHE_ECDSA_WITH_AES_128_CCM (RFC 6655)
• TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 (RFC 6655)
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
• TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA (RFC 8422)
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (RFC 8422)

PSK

• TLS_PSK_WITH_AES_128_CCM (RFC 6655)
• TLS_PSK_WITH_AES_128_CCM_8 (RFC 6655)
• TLS_PSK_WITH_AES_256_CCM_8 (RFC 6655)
• TLS_PSK_WITH_AES_128_GCM_SHA256 (RFC 5487)
• TLS_PSK_WITH_AES_128_CBC_SHA256 (RFC 5487)

ECDHE & PSK

• TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 (RFC 5489)

Planned Features

• Chacha20Poly1305

Excluded Features

• DTLS 1.0
• Renegotiation
• Compression

Using

This library needs at least Go 1.13, and you should have Go modules enabled.

Pion DTLS

For a DTLS 1.2 Server that listens on 127.0.0.1:4444

go run examples/listen/selfsign/main.go

For a DTLS 1.2 Client that connects to 127.0.0.1:4444

go run examples/dial/selfsign/main.go

OpenSSL

Pion DTLS can connect to itself and OpenSSL.

  // Generate a certificate
  openssl ecparam -out key.pem -name prime256v1 -genkey
  openssl req -new -sha256 -key key.pem -out server.csr
  openssl x509 -req -sha256 -days 365 -in server.csr -signkey key.pem -out cert.pem

  // Use with examples/dial/selfsign/main.go
  openssl s_server -dtls1_2 -cert cert.pem -key key.pem -accept 4444

  // Use with examples/listen/selfsign/main.go
  openssl s_client -dtls1_2 -connect 127.0.0.1:4444 -debug -cert cert.pem -key key.pem

Using with PSK

Pion DTLS also comes with examples that do key exchange via PSK

Pion DTLS

go run examples/listen/psk/main.go

go run examples/dial/psk/main.go

OpenSSL

  // Use with examples/dial/psk/main.go
  openssl s_server -dtls1_2 -accept 4444 -nocert -psk abc123 -cipher PSK-AES128-CCM8

  // Use with examples/listen/psk/main.go
  openssl s_client -dtls1_2 -connect 127.0.0.1:4444 -psk abc123 -cipher PSK-AES128-CCM8

Community

Pion has an active community on the Slack.

Follow the Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package dtls implements Datagram Transport Layer Security (DTLS) 1.2

Index

• Constants
• Variables
• func CipherSuiteName(id CipherSuiteID) string
• func CipherSuites() []*tls.CipherSuite
• func InsecureCipherSuites() []*tls.CipherSuite
• func Listen(network string, laddr *net.UDPAddr, config *Config) (net.Listener, error)
• func NewListener(inner dtlsnet.PacketListener, config *Config) (net.Listener, error)
• func OnlySendCIDGenerator() func() []byte
• func RandomCIDGenerator(size int) func() []byte
• type CertificateRequestInfo
  • func (cri *CertificateRequestInfo) SupportsCertificate(c *tls.Certificate) error
• type CipherSuite
• type CipherSuiteAuthenticationType
• type CipherSuiteID
• type CipherSuiteKeyExchangeAlgorithm
• type ClientAuthType
• type ClientHelloInfo
• type Config
• type Conn
  • func Client(conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)
  • func ClientWithContext(ctx context.Context, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)
  • func Dial(network string, rAddr *net.UDPAddr, config *Config) (*Conn, error)
  • func DialWithContext(ctx context.Context, network string, rAddr *net.UDPAddr, config *Config) (*Conn, error)
  • func Resume(state *State, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)
  • func Server(conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)
  • func ServerWithContext(ctx context.Context, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) ConnectionState() State
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(p []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SelectedSRTPProtectionProfile() (SRTPProtectionProfile, bool)
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(p []byte) (int, error)
• type ExtendedMasterSecretType
• type FatalError
• type HandshakeError
• type InternalError
• type PSKCallback
• type SRTPProtectionProfile
• type Session
• type SessionStore
• type State
  • func (s *State) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)
  • func (s *State) MarshalBinary() ([]byte, error)
  • func (s *State) UnmarshalBinary(data []byte) error
• type TemporaryError
• type TimeoutError

Constants

const VersionDTLS12 = 0xfefd

VersionDTLS12 is the DTLS version in the same style as VersionTLSXX from crypto/tls

Variables

var (
	ErrConnClosed = &FatalError{Err: errors.New("conn is closed")} //nolint:goerr113

)

Typed errors

Functions

func CipherSuiteName

func CipherSuiteName(id CipherSuiteID) string

CipherSuiteName provides the same functionality as tls.CipherSuiteName that appeared first in Go 1.14.

Our implementation differs slightly in that it takes in a CiperSuiteID, like the rest of our library, instead of a uint16 like crypto/tls.

func CipherSuites

func CipherSuites() []*tls.CipherSuite

CipherSuites returns a list of cipher suites currently implemented by this package, excluding those with security issues, which are returned by InsecureCipherSuites.

func InsecureCipherSuites

func InsecureCipherSuites() []*tls.CipherSuite

InsecureCipherSuites returns a list of cipher suites currently implemented by this package and which have security issues.

func Listen

func Listen(network string, laddr *net.UDPAddr, config *Config) (net.Listener, error)

Listen creates a DTLS listener

func NewListener

func NewListener(inner dtlsnet.PacketListener, config *Config) (net.Listener, error)

NewListener creates a DTLS listener which accepts connections from an inner Listener.

func OnlySendCIDGenerator

func OnlySendCIDGenerator() func() []byte

OnlySendCIDGenerator enables sending Connection IDs negotiated with a peer, but indicates to the peer that sending Connection IDs in return is not necessary.

func RandomCIDGenerator

func RandomCIDGenerator(size int) func() []byte

RandomCIDGenerator is a random Connection ID generator where CID is the specified size. Specifying a size of 0 will indicate to peers that sending a Connection ID is not necessary.

Types

type CertificateRequestInfo

type CertificateRequestInfo struct {
	// AcceptableCAs contains zero or more, DER-encoded, X.501
	// Distinguished Names. These are the names of root or intermediate CAs
	// that the server wishes the returned certificate to be signed by. An
	// empty slice indicates that the server has no preference.
	AcceptableCAs [][]byte
}

CertificateRequestInfo contains information from a server's CertificateRequest message, which is used to demand a certificate and proof of control from a client.

func (*CertificateRequestInfo) SupportsCertificate

func (cri *CertificateRequestInfo) SupportsCertificate(c *tls.Certificate) error

SupportsCertificate returns nil if the provided certificate is supported by the server that sent the CertificateRequest. Otherwise, it returns an error describing the reason for the incompatibility. NOTE: original src: https://github.com/golang/go/blob/29b9a328d268d53833d2cc063d1d8b4bf6852675/src/crypto/tls/common.go#L1273

type CipherSuite

type CipherSuite interface {
	// String of CipherSuite, only used for logging
	String() string

	// ID of CipherSuite.
	ID() CipherSuiteID

	// What type of Certificate does this CipherSuite use
	CertificateType() clientcertificate.Type

	// What Hash function is used during verification
	HashFunc() func() hash.Hash

	// AuthenticationType controls what authentication method is using during the handshake
	AuthenticationType() CipherSuiteAuthenticationType

	// KeyExchangeAlgorithm controls what exchange algorithm is using during the handshake
	KeyExchangeAlgorithm() CipherSuiteKeyExchangeAlgorithm

	// ECC (Elliptic Curve Cryptography) determines whether ECC extesions will be send during handshake.
	// https://datatracker.ietf.org/doc/html/rfc4492#page-10
	ECC() bool

	// Called when keying material has been generated, should initialize the internal cipher
	Init(masterSecret, clientRandom, serverRandom []byte, isClient bool) error
	IsInitialized() bool
	Encrypt(pkt *recordlayer.RecordLayer, raw []byte) ([]byte, error)
	Decrypt(h recordlayer.Header, in []byte) ([]byte, error)
}

CipherSuite is an interface that all DTLS CipherSuites must satisfy

type CipherSuiteAuthenticationType

type CipherSuiteAuthenticationType = ciphersuite.AuthenticationType

CipherSuiteAuthenticationType controls what authentication method is using during the handshake for a CipherSuite

const (
	CipherSuiteAuthenticationTypeCertificate  CipherSuiteAuthenticationType = ciphersuite.AuthenticationTypeCertificate
	CipherSuiteAuthenticationTypePreSharedKey CipherSuiteAuthenticationType = ciphersuite.AuthenticationTypePreSharedKey
	CipherSuiteAuthenticationTypeAnonymous    CipherSuiteAuthenticationType = ciphersuite.AuthenticationTypeAnonymous
)

AuthenticationType Enums

type CipherSuiteID

type CipherSuiteID = ciphersuite.ID

CipherSuiteID is an ID for our supported CipherSuites

const (
	// AES-128-CCM
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM   CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_128_CCM   //nolint:revive,stylecheck
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 //nolint:revive,stylecheck

	// AES-128-GCM-SHA256
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 //nolint:revive,stylecheck
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   CipherSuiteID = ciphersuite.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   //nolint:revive,stylecheck

	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 //nolint:revive,stylecheck
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   CipherSuiteID = ciphersuite.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   //nolint:revive,stylecheck

	// AES-256-CBC-SHA
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA //nolint:revive,stylecheck
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA   CipherSuiteID = ciphersuite.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA   //nolint:revive,stylecheck

	TLS_PSK_WITH_AES_128_CCM        CipherSuiteID = ciphersuite.TLS_PSK_WITH_AES_128_CCM        //nolint:revive,stylecheck
	TLS_PSK_WITH_AES_128_CCM_8      CipherSuiteID = ciphersuite.TLS_PSK_WITH_AES_128_CCM_8      //nolint:revive,stylecheck
	TLS_PSK_WITH_AES_256_CCM_8      CipherSuiteID = ciphersuite.TLS_PSK_WITH_AES_256_CCM_8      //nolint:revive,stylecheck
	TLS_PSK_WITH_AES_128_GCM_SHA256 CipherSuiteID = ciphersuite.TLS_PSK_WITH_AES_128_GCM_SHA256 //nolint:revive,stylecheck
	TLS_PSK_WITH_AES_128_CBC_SHA256 CipherSuiteID = ciphersuite.TLS_PSK_WITH_AES_128_CBC_SHA256 //nolint:revive,stylecheck

	TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 CipherSuiteID = ciphersuite.TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 //nolint:revive,stylecheck
)

Supported Cipher Suites

type CipherSuiteKeyExchangeAlgorithm

type CipherSuiteKeyExchangeAlgorithm = ciphersuite.KeyExchangeAlgorithm

CipherSuiteKeyExchangeAlgorithm controls what exchange algorithm is using during the handshake for a CipherSuite

const (
	CipherSuiteKeyExchangeAlgorithmNone  CipherSuiteKeyExchangeAlgorithm = ciphersuite.KeyExchangeAlgorithmNone
	CipherSuiteKeyExchangeAlgorithmPsk   CipherSuiteKeyExchangeAlgorithm = ciphersuite.KeyExchangeAlgorithmPsk
	CipherSuiteKeyExchangeAlgorithmEcdhe CipherSuiteKeyExchangeAlgorithm = ciphersuite.KeyExchangeAlgorithmEcdhe
)

CipherSuiteKeyExchangeAlgorithm Bitmask

type ClientAuthType

type ClientAuthType int

ClientAuthType declares the policy the server will follow for TLS Client Authentication.

const (
	NoClientCert ClientAuthType = iota
	RequestClientCert
	RequireAnyClientCert
	VerifyClientCertIfGiven
	RequireAndVerifyClientCert
)

ClientAuthType enums

type ClientHelloInfo

type ClientHelloInfo struct {
	// ServerName indicates the name of the server requested by the client
	// in order to support virtual hosting. ServerName is only set if the
	// client is using SNI (see RFC 4366, Section 3.1).
	ServerName string

	// CipherSuites lists the CipherSuites supported by the client (e.g.
	// TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).
	CipherSuites []CipherSuiteID
}

ClientHelloInfo contains information from a ClientHello message in order to guide application logic in the GetCertificate.

type Config

type Config struct {
	// Certificates contains certificate chain to present to the other side of the connection.
	// Server MUST set this if PSK is non-nil
	// client SHOULD sets this so CertificateRequests can be handled if PSK is non-nil
	Certificates []tls.Certificate

	// CipherSuites is a list of supported cipher suites.
	// If CipherSuites is nil, a default list is used
	CipherSuites []CipherSuiteID

	// CustomCipherSuites is a list of CipherSuites that can be
	// provided by the user. This allow users to user Ciphers that are reserved
	// for private usage.
	CustomCipherSuites func() []CipherSuite

	// SignatureSchemes contains the signature and hash schemes that the peer requests to verify.
	SignatureSchemes []tls.SignatureScheme

	// SRTPProtectionProfiles are the supported protection profiles
	// Clients will send this via use_srtp and assert that the server properly responds
	// Servers will assert that clients send one of these profiles and will respond as needed
	SRTPProtectionProfiles []SRTPProtectionProfile

	// ClientAuth determines the server's policy for
	// TLS Client Authentication. The default is NoClientCert.
	ClientAuth ClientAuthType

	// RequireExtendedMasterSecret determines if the "Extended Master Secret" extension
	// should be disabled, requested, or required (default requested).
	ExtendedMasterSecret ExtendedMasterSecretType

	// FlightInterval controls how often we send outbound handshake messages
	// defaults to time.Second
	FlightInterval time.Duration

	// PSK sets the pre-shared key used by this DTLS connection
	// If PSK is non-nil only PSK CipherSuites will be used
	PSK             PSKCallback
	PSKIdentityHint []byte

	// InsecureSkipVerify controls whether a client verifies the
	// server's certificate chain and host name.
	// If InsecureSkipVerify is true, TLS accepts any certificate
	// presented by the server and any host name in that certificate.
	// In this mode, TLS is susceptible to man-in-the-middle attacks.
	// This should be used only for testing.
	InsecureSkipVerify bool

	// InsecureHashes allows the use of hashing algorithms that are known
	// to be vulnerable.
	InsecureHashes bool

	// VerifyPeerCertificate, if not nil, is called after normal
	// certificate verification by either a client or server. It
	// receives the certificate provided by the peer and also a flag
	// that tells if normal verification has succeedded. If it returns a
	// non-nil error, the handshake is aborted and that error results.
	//
	// If normal verification fails then the handshake will abort before
	// considering this callback. If normal verification is disabled by
	// setting InsecureSkipVerify, or (for a server) when ClientAuth is
	// RequestClientCert or RequireAnyClientCert, then this callback will
	// be considered but the verifiedChains will always be nil.
	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error

	// VerifyConnection, if not nil, is called after normal certificate
	// verification/PSK and after VerifyPeerCertificate by either a TLS client
	// or server. If it returns a non-nil error, the handshake is aborted
	// and that error results.
	//
	// If normal verification fails then the handshake will abort before
	// considering this callback. This callback will run for all connections
	// regardless of InsecureSkipVerify or ClientAuth settings.
	VerifyConnection func(*State) error

	// RootCAs defines the set of root certificate authorities
	// that one peer uses when verifying the other peer's certificates.
	// If RootCAs is nil, TLS uses the host's root CA set.
	RootCAs *x509.CertPool

	// ClientCAs defines the set of root certificate authorities
	// that servers use if required to verify a client certificate
	// by the policy in ClientAuth.
	ClientCAs *x509.CertPool

	// ServerName is used to verify the hostname on the returned
	// certificates unless InsecureSkipVerify is given.
	ServerName string

	LoggerFactory logging.LoggerFactory

	// ConnectContextMaker is a function to make a context used in Dial(),
	// Client(), Server(), and Accept(). If nil, the default ConnectContextMaker
	// is used. It can be implemented as following.
	//
	// 	func ConnectContextMaker() (context.Context, func()) {
	// 		return context.WithTimeout(context.Background(), 30*time.Second)
	// 	}
	ConnectContextMaker func() (context.Context, func())

	// MTU is the length at which handshake messages will be fragmented to
	// fit within the maximum transmission unit (default is 1200 bytes)
	MTU int

	// ReplayProtectionWindow is the size of the replay attack protection window.
	// Duplication of the sequence number is checked in this window size.
	// Packet with sequence number older than this value compared to the latest
	// accepted packet will be discarded. (default is 64)
	ReplayProtectionWindow int

	// KeyLogWriter optionally specifies a destination for TLS master secrets
	// in NSS key log format that can be used to allow external programs
	// such as Wireshark to decrypt TLS connections.
	// See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
	// Use of KeyLogWriter compromises security and should only be
	// used for debugging.
	KeyLogWriter io.Writer

	// SessionStore is the container to store session for resumption.
	SessionStore SessionStore

	// List of application protocols the peer supports, for ALPN
	SupportedProtocols []string

	// List of Elliptic Curves to use
	//
	// If an ECC ciphersuite is configured and EllipticCurves is empty
	// it will default to X25519, P-256, P-384 in this specific order.
	EllipticCurves []elliptic.Curve

	// GetCertificate returns a Certificate based on the given
	// ClientHelloInfo. It will only be called if the client supplies SNI
	// information or if Certificates is empty.
	//
	// If GetCertificate is nil or returns nil, then the certificate is
	// retrieved from NameToCertificate. If NameToCertificate is nil, the
	// best element of Certificates will be used.
	GetCertificate func(*ClientHelloInfo) (*tls.Certificate, error)

	// GetClientCertificate, if not nil, is called when a server requests a
	// certificate from a client. If set, the contents of Certificates will
	// be ignored.
	//
	// If GetClientCertificate returns an error, the handshake will be
	// aborted and that error will be returned. Otherwise
	// GetClientCertificate must return a non-nil Certificate. If
	// Certificate.Certificate is empty then no certificate will be sent to
	// the server. If this is unacceptable to the server then it may abort
	// the handshake.
	GetClientCertificate func(*CertificateRequestInfo) (*tls.Certificate, error)

	// InsecureSkipVerifyHello, if true and when acting as server, allow client to
	// skip hello verify phase and receive ServerHello after initial ClientHello.
	// This have implication on DoS attack resistance.
	InsecureSkipVerifyHello bool

	// ConnectionIDGenerator generates connection identifiers that should be
	// sent by the remote party if it supports the DTLS Connection Identifier
	// extension, as determined during the handshake. Generated connection
	// identifiers must always have the same length. Returning a zero-length
	// connection identifier indicates that the local party supports sending
	// connection identifiers but does not require the remote party to send
	// them. A nil ConnectionIDGenerator indicates that connection identifiers
	// are not supported.
	// https://datatracker.ietf.org/doc/html/rfc9146
	ConnectionIDGenerator func() []byte

	// PaddingLengthGenerator generates the number of padding bytes used to
	// inflate ciphertext size in order to obscure content size from observers.
	// The length of the content is passed to the generator such that both
	// deterministic and random padding schemes can be applied while not
	// exceeding maximum record size.
	// If no PaddingLengthGenerator is specified, padding will not be applied.
	// https://datatracker.ietf.org/doc/html/rfc9146#section-4
	PaddingLengthGenerator func(uint) uint
}

Config is used to configure a DTLS client or server. After a Config is passed to a DTLS function it must not be modified.

type Conn

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

Conn represents a DTLS connection

func Client

func Client(conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)

Client establishes a DTLS connection over an existing connection. Connection handshake will timeout using ConnectContextMaker in the Config. If you want to specify the timeout duration, use ClientWithContext() instead.

func ClientWithContext

func ClientWithContext(ctx context.Context, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)

ClientWithContext establishes a DTLS connection over an existing connection.

func Dial

func Dial(network string, rAddr *net.UDPAddr, config *Config) (*Conn, error)

Dial connects to the given network address and establishes a DTLS connection on top. Connection handshake will timeout using ConnectContextMaker in the Config. If you want to specify the timeout duration, use DialWithContext() instead.

func DialWithContext

func DialWithContext(ctx context.Context, network string, rAddr *net.UDPAddr, config *Config) (*Conn, error)

DialWithContext connects to the given network address and establishes a DTLS connection on top.

func Resume

func Resume(state *State, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)

Resume imports an already established dtls connection using a specific dtls state

func Server

func Server(conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)

Server listens for incoming DTLS connections. Connection handshake will timeout using ConnectContextMaker in the Config. If you want to specify the timeout duration, use ServerWithContext() instead.

func ServerWithContext

func ServerWithContext(ctx context.Context, conn net.PacketConn, rAddr net.Addr, config *Config) (*Conn, error)

ServerWithContext listens for incoming DTLS connections.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() State

ConnectionState returns basic DTLS details about the connection. Note that this replaced the `Export` function of v1.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr implements net.Conn.LocalAddr

func (*Conn) Read

func (c *Conn) Read(p []byte) (n int, err error)

Read reads data from the connection.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr implements net.Conn.RemoteAddr

func (*Conn) SelectedSRTPProtectionProfile

func (c *Conn) SelectedSRTPProtectionProfile() (SRTPProtectionProfile, bool)

SelectedSRTPProtectionProfile returns the selected SRTPProtectionProfile

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline implements net.Conn.SetDeadline

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline implements net.Conn.SetReadDeadline

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements net.Conn.SetWriteDeadline

func (*Conn) Write

func (c *Conn) Write(p []byte) (int, error)

Write writes len(p) bytes from p to the DTLS connection

type ExtendedMasterSecretType

type ExtendedMasterSecretType int

ExtendedMasterSecretType declares the policy the client and server will follow for the Extended Master Secret extension

const (
	RequestExtendedMasterSecret ExtendedMasterSecretType = iota
	RequireExtendedMasterSecret
	DisableExtendedMasterSecret
)

ExtendedMasterSecretType enums

type FatalError

type FatalError = protocol.FatalError

FatalError indicates that the DTLS connection is no longer available. It is mainly caused by wrong configuration of server or client.

type HandshakeError

type HandshakeError = protocol.HandshakeError

HandshakeError indicates that the handshake failed.

type InternalError

type InternalError = protocol.InternalError

InternalError indicates and internal error caused by the implementation, and the DTLS connection is no longer available. It is mainly caused by bugs or tried to use unimplemented features.

type PSKCallback

type PSKCallback func([]byte) ([]byte, error)

PSKCallback is called once we have the remote's PSKIdentityHint. If the remote provided none it will be nil

type SRTPProtectionProfile

type SRTPProtectionProfile = extension.SRTPProtectionProfile

SRTPProtectionProfile defines the parameters and options that are in effect for the SRTP processing https://tools.ietf.org/html/rfc5764#section-4.1.2

const (
	SRTP_AES128_CM_HMAC_SHA1_80 SRTPProtectionProfile = extension.SRTP_AES128_CM_HMAC_SHA1_80 // nolint:revive,stylecheck
	SRTP_AES128_CM_HMAC_SHA1_32 SRTPProtectionProfile = extension.SRTP_AES128_CM_HMAC_SHA1_32 // nolint:revive,stylecheck
	SRTP_AEAD_AES_128_GCM       SRTPProtectionProfile = extension.SRTP_AEAD_AES_128_GCM       // nolint:revive,stylecheck
	SRTP_AEAD_AES_256_GCM       SRTPProtectionProfile = extension.SRTP_AEAD_AES_256_GCM       // nolint:revive,stylecheck
)

type Session

type Session struct {
	// ID store session id
	ID []byte
	// Secret store session master secret
	Secret []byte
}

Session store data needed in resumption

type SessionStore

type SessionStore interface {
	// Set save a session.
	// For client, use server name as key.
	// For server, use session id.
	Set(key []byte, s Session) error
	// Get fetch a session.
	Get(key []byte) (Session, error)
	// Del clean saved session.
	Del(key []byte) error
}

SessionStore defines methods needed for session resumption.

type State

type State struct {
	CipherSuiteID CipherSuiteID

	PeerCertificates [][]byte
	IdentityHint     []byte
	SessionID        []byte

	NegotiatedProtocol string
	// contains filtered or unexported fields
}

State holds the dtls connection state and implements both encoding.BinaryMarshaler and encoding.BinaryUnmarshaler

func (*State) ExportKeyingMaterial

func (s *State) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)

ExportKeyingMaterial returns length bytes of exported key material in a new slice as defined in RFC 5705. This allows protocols to use DTLS for key establishment, but then use some of the keying material for their own purposes

func (*State) MarshalBinary

func (s *State) MarshalBinary() ([]byte, error)

MarshalBinary is a binary.BinaryMarshaler.MarshalBinary implementation

func (*State) UnmarshalBinary

func (s *State) UnmarshalBinary(data []byte) error

UnmarshalBinary is a binary.BinaryUnmarshaler.UnmarshalBinary implementation

type TemporaryError

type TemporaryError = protocol.TemporaryError

TemporaryError indicates that the DTLS connection is still available, but the request was failed temporary.

type TimeoutError

type TimeoutError = protocol.TimeoutError

TimeoutError indicates that the request was timed out.