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.

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)

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

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 net.Listener, config *Config) (net.Listener, error)
• type CipherSuite
• type CipherSuiteAuthenticationType
• type CipherSuiteID
• type ClientAuthType
• type Config
• type Conn
  • func Client(conn net.Conn, config *Config) (*Conn, error)
  • func ClientWithContext(ctx context.Context, conn net.Conn, 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.Conn, config *Config) (*Conn, error)
  • func Server(conn net.Conn, config *Config) (*Conn, error)
  • func ServerWithContext(ctx context.Context, conn net.Conn, 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 net.Listener, config *Config) (net.Listener, error)

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

Types

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

	// 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(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:golint,stylecheck
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 CipherSuiteID = ciphersuite.TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 //nolint:golint,stylecheck

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

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

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

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

Supported Cipher Suites

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

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

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.Conn, 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.Conn, 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.Conn, config *Config) (*Conn, error)

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

func Server

func Server(conn net.Conn, 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.Conn, 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
	SRTP_AES128_CM_HMAC_SHA1_32 SRTPProtectionProfile = extension.SRTP_AES128_CM_HMAC_SHA1_32 // nolint
	SRTP_AEAD_AES_128_GCM       SRTPProtectionProfile = extension.SRTP_AEAD_AES_128_GCM       // nolint
	SRTP_AEAD_AES_256_GCM       SRTPProtectionProfile = extension.SRTP_AEAD_AES_256_GCM       // nolint
)

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