dtls

README

Pion DTLS

A Go implementation of DTLS

Go DTLS 1.2 implementation. The original user is pion-WebRTC, but we would love to see it work for everyone.

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
• Forward secrecy using ECDHE; with curve25519 and nistp256 (non-PFS will not be supported)
• AES_128_GCM, AES_256_CBC
• Packet loss and re-ordering is handled during handshaking
• Key export (RFC5705)

Planned Features

• Extended master secret support (RFC7627)
• Chacha20Poly1305

Excluded Features

• DTLS 1.0
• Renegotiation
• Compression

Pion DTLS

For a DTLS 1.2 Server that listens on 127.0.0.1:4444

go run examples/listen/main.go

For a DTLS 1.2 Client that connects to 127.0.0.1:4444

go run examples/dial/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/main.go
  openssl s_server -dtls1_2 -cert cert.pem -key key.pem -accept 4444

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

Contributing

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

• Sean DuBois - Original Author
• Michiel De Backker - Public API
• Chris Hiszpanski - Support Signature Algorithms Extension
• Iñigo Garcia Olaizola - Support serialization and resumption"
• Daniele Sluijters - AES-CCM support
• Jin Lei - Logging
• Hugo Arregui
• Lander Noterman
• Aleksandr Razumov - Fuzzing

License

MIT License - see LICENSE for full text

Documentation

Index

• Variables
• func Fingerprint(cert *x509.Certificate, algo HashAlgorithm) (string, error)
• func GenerateSelfSigned() (*x509.Certificate, crypto.PrivateKey, error)
• type CipherSuiteID
• type ClientAuthType
• type Config
• type Conn
  • func Client(conn net.Conn, config *Config) (*Conn, error)
  • func Dial(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 (c *Conn) Close() error
  • func (c *Conn) Export() (*State, net.Conn, error)
  • func (c *Conn) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)
  • 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) RemoteCertificate() *x509.Certificate
  • 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 HashAlgorithm
  • func HashAlgorithmString(s string) (HashAlgorithm, error)
  • func (h HashAlgorithm) String() string
• type Listener
  • func Listen(network string, laddr *net.UDPAddr, config *Config) (*Listener, error)
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
• type PSKCallback
• type SRTPProtectionProfile
• type State
  • func (s *State) MarshalBinary() ([]byte, error)
  • func (s *State) UnmarshalBinary(data []byte) error

Variables

var (
	ErrConnClosed = errors.New("dtls: conn is closed")
)

Typed errors

Functions

func Fingerprint

func Fingerprint(cert *x509.Certificate, algo HashAlgorithm) (string, error)

Fingerprint creates a fingerprint for a certificate using the specified hash algorithm

func GenerateSelfSigned

func GenerateSelfSigned() (*x509.Certificate, crypto.PrivateKey, error)

GenerateSelfSigned creates a self-signed certificate

Types

type CipherSuiteID

type CipherSuiteID uint16

CipherSuiteID is an ID for our supported CipherSuites

const (
	// 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 = 0x0035
)

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
)

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
	Certificate *x509.Certificate

	// PrivateKey contains matching private key for the certificate
	// only ECDSA is supported
	PrivateKey crypto.PrivateKey

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

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

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

	LoggerFactory logging.LoggerFactory
}

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 conn

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

func Resume

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

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

func Server

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

Server listens for incoming DTLS connections

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) Export

func (c *Conn) Export() (*State, net.Conn, error)

Export extracts dtls state and inner connection from an already handshaked dtls conn

func (*Conn) ExportKeyingMaterial

func (c *Conn) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)

ExportKeyingMaterial from https://tools.ietf.org/html/rfc5705 This allows protocols to use DTLS for key establishment, but then use some of the keying material for their own purposes

func (*Conn) LocalAddr

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

LocalAddr is a stub

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 is a stub

func (*Conn) RemoteCertificate

func (c *Conn) RemoteCertificate() *x509.Certificate

RemoteCertificate exposes the remote certificate

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 is a stub

func (*Conn) SetReadDeadline

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

SetReadDeadline is a stub

func (*Conn) SetWriteDeadline

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

SetWriteDeadline is a stub

func (*Conn) Write

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

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

type HashAlgorithm

type HashAlgorithm uint16

HashAlgorithm is used to indicate the hash algorithm used https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

const (
	// HashAlgorithmMD2    HashAlgorithm = 0 // Blacklisted
	HashAlgorithmMD5    HashAlgorithm = 1 // Blacklisted
	HashAlgorithmSHA1   HashAlgorithm = 2 // Blacklisted
	HashAlgorithmSHA224 HashAlgorithm = 3
	HashAlgorithmSHA256 HashAlgorithm = 4
	HashAlgorithmSHA384 HashAlgorithm = 5
	HashAlgorithmSHA512 HashAlgorithm = 6
)

Supported hash hash algorithms

func HashAlgorithmString

func HashAlgorithmString(s string) (HashAlgorithm, error)

HashAlgorithmString allows looking up a HashAlgorithm by it's string representation

func (HashAlgorithm) String

func (h HashAlgorithm) String() string

String makes HashAlgorithm printable

type Listener

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

Listener represents a DTLS listener

func Listen

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

Listen creates a DTLS listener

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener. You have to either close or read on all connection that are created.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the listener. Any blocked Accept operations will be unblocked and return errors. Already Accepted connections are not closed.

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
)

type State

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

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

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