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
• Packet loss and re-ordering is handled during handshaking
• Key export (RFC5705)

Planned Features

• Extended master secret support (RFC7627)
• Chacha20Poly1305
• AES_256_CBC

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

License

MIT License - see LICENSE for full text

Documentation

Index

• Constants
• Variables
• func Fingerprint(cert *x509.Certificate, algo HashAlgorithm) (string, error)
• func GenerateSelfSigned() (*x509.Certificate, crypto.PrivateKey, error)
• 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 Server(conn net.Conn, config *Config) (*Conn, error)
  • func (c *Conn) Close() 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) 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

Constants

const (
	SRTP_AES128_CM_HMAC_SHA1_80 srtpProtectionProfile = 0x0001 // nolint
)

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 Config

type Config struct {
	Certificate *x509.Certificate
	PrivateKey  crypto.PrivateKey
}

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