dtls

package module
v2.0.0-rc.3.0...-cfbd00d Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2020 License: MIT Imports: 43 Imported by: 0

README


Pion DTLS

A Go implementation of DTLS

Pion DTLS Sourcegraph Widget Slack Widget
Build Status GoDoc Coverage Status Go Report Card Codacy Badge


Native DTLS 1.2 implementation in the Go programming language.

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

Goals/Progress

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

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)

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_CBC_SHA (RFC 8422)
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (RFC 8422)
PSK

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

View Source 
const (

	// VersionDTLS12 is the DTLS version in the same style as
	// VersionTLSXX from crypto/tls
	VersionDTLS12 = 0xfefd
)

Variables

View Source 
var (
	ErrConnClosed = &FatalError{errors.New("conn is closed")}
)

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 CipherSuiteID 

type CipherSuiteID uint16

CipherSuiteID is an ID for our supported CipherSuites 

const (
	// AES-128-CCM
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM   CipherSuiteID = 0xc0ac
	TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 CipherSuiteID = 0xc0ae

	// AES-128-GCM-SHA256
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 CipherSuiteID = 0xc02b
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   CipherSuiteID = 0xc02f

	// AES-256-CBC-SHA
	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA CipherSuiteID = 0xc00a
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA   CipherSuiteID = 0xc014

	TLS_PSK_WITH_AES_128_CCM        CipherSuiteID = 0xc0a4
	TLS_PSK_WITH_AES_128_CCM_8      CipherSuiteID = 0xc0a8
	TLS_PSK_WITH_AES_128_GCM_SHA256 CipherSuiteID = 0x00a8
)

Supported Cipher Suites

func (CipherSuiteID) String 

func (c CipherSuiteID) String() string

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

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

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 struct {
	Err error
}

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

func (*FatalError) Error 

func (e *FatalError) Error() string

func (*FatalError) Temporary 

func (*FatalError) Temporary() bool

Temporary implements net.Error.Temporary()

func (*FatalError) Timeout 

func (*FatalError) Timeout() bool

Timeout implements net.Error.Timeout()

func (*FatalError) Unwrap 

func (e *FatalError) Unwrap() error

Unwrap implements Go1.13 error unwrapper.

type HandshakeError 

type HandshakeError struct {
	Err error
}

HandshakeError indicates that the handshake failed.

func (*HandshakeError) Error 

func (e *HandshakeError) Error() string

func (*HandshakeError) Temporary 

func (e *HandshakeError) Temporary() bool

Temporary implements net.Error.Temporary()

func (*HandshakeError) Timeout 

func (e *HandshakeError) Timeout() bool

Timeout implements net.Error.Timeout()

func (*HandshakeError) Unwrap 

func (e *HandshakeError) Unwrap() error

Unwrap implements Go1.13 error unwrapper.

type InternalError 

type InternalError struct {
	Err error
}

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.

func (*InternalError) Error 

func (e *InternalError) Error() string

func (*InternalError) Temporary 

func (*InternalError) Temporary() bool

Temporary implements net.Error.Temporary()

func (*InternalError) Timeout 

func (*InternalError) Timeout() bool

Timeout implements net.Error.Timeout()

func (*InternalError) Unwrap 

func (e *InternalError) Unwrap() error

Unwrap implements Go1.13 error unwrapper.

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 uint16

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 = 0x0001 // nolint
	SRTP_AES128_CM_HMAC_SHA1_32 SRTPProtectionProfile = 0x0002 // nolint
	SRTP_AEAD_AES_128_GCM       SRTPProtectionProfile = 0x0007 // nolint
	SRTP_AEAD_AES_256_GCM       SRTPProtectionProfile = 0x0008 // nolint
)

type State 

type State struct {
	PeerCertificates [][]byte
	// 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 struct {
	Err error
}

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

func (*TemporaryError) Error 

func (e *TemporaryError) Error() string

func (*TemporaryError) Temporary 

func (*TemporaryError) Temporary() bool

Temporary implements net.Error.Temporary()

func (*TemporaryError) Timeout 

func (*TemporaryError) Timeout() bool

Timeout implements net.Error.Timeout()

func (*TemporaryError) Unwrap 

func (e *TemporaryError) Unwrap() error

Unwrap implements Go1.13 error unwrapper.

type TimeoutError 

type TimeoutError struct {
	Err error
}

TimeoutError indicates that the request was timed out.

func (*TimeoutError) Error 

func (e *TimeoutError) Error() string

func (*TimeoutError) Temporary 

func (*TimeoutError) Temporary() bool

Temporary implements net.Error.Temporary()

func (*TimeoutError) Timeout 

func (*TimeoutError) Timeout() bool

Timeout implements net.Error.Timeout()

func (*TimeoutError) Unwrap 

func (e *TimeoutError) Unwrap() error

Unwrap implements Go1.13 error unwrapper.

Source Files

View all Source files

Directories

Path Synopsis
Package e2e contains end to end tests for pion/dtls
 Package e2e contains end to end tests for pion/dtls
examples
dial/psk
dial/selfsign
dial/verify
listen/psk
listen/selfsign
listen/verify
util
Package util provides auxiliary utilities used in examples
 Package util provides auxiliary utilities used in examples
internal
closer
Package closer provides signaling channel for shutdown
 Package closer provides signaling channel for shutdown
net/connctx
Package connctx wraps net.Conn using context.Context.
 Package connctx wraps net.Conn using context.Context.
net/dpipe
Package dpipe provides the pipe works like datagram protocol on memory.
 Package dpipe provides the pipe works like datagram protocol on memory.
pkg
crypto/ccm
Package ccm implements a CCM, Counter with CBC-MAC as per RFC 3610.
 Package ccm implements a CCM, Counter with CBC-MAC as per RFC 3610.
crypto/fingerprint
Package fingerprint provides a helper to create fingerprint string from certificate
 Package fingerprint provides a helper to create fingerprint string from certificate
crypto/selfsign
Package selfsign is a test helper that generates self signed certificate.
 Package selfsign is a test helper that generates self signed certificate.

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.