dtls

package module
v1.5.4 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2019 License: MIT Imports: 34 Imported by: 24

README


Pion DTLS

A Go implementation of DTLS

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


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
  • 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_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
  • TLS_PSK_WITH_AES_128_CCM_8 (RFC 6655)
  • TLS_PSK_WITH_AES_128_GCM_SHA256 (RFC 5487)

Planned Features

  • Chacha20Poly1305

Excluded Features

  • DTLS 1.0
  • Renegotiation
  • Compression

Using

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

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

Index

Constants

This section is empty.

Variables

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

Typed errors

Functions

func ConnectTimeoutOption added in v1.5.2 

func ConnectTimeoutOption(timeout time.Duration) *time.Duration

ConnectTimeoutOption simply provides a wrapper for creating a *time.Duration

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

func SelfSign added in v1.5.4 

func SelfSign(key crypto.PrivateKey) (*x509.Certificate, error)

SelfSign creates a self-signed certificate from a elliptic curve key

Types

type CipherSuiteID added in v1.3.5 

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

	TLS_PSK_WITH_AES_128_CCM_8      CipherSuiteID = 0xc0a8
	TLS_PSK_WITH_AES_128_GCM_SHA256 CipherSuiteID = 0x00a8
)

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 Closer added in v1.5.2 

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

Closer allows for each signaling a channel for shutdown

func NewCloser added in v1.5.2 

func NewCloser() *Closer

NewCloser creates a new instance of Closer

func NewCloserWithParent added in v1.5.2 

func NewCloserWithParent(ctx context.Context) *Closer

NewCloserWithParent creates a new instance of Closer with a parent context

func (*Closer) Close added in v1.5.2 

func (c *Closer) Close()

Close sends a signal to trigger the ctx done channel

func (*Closer) Done added in v1.5.2 

func (c *Closer) Done() <-chan struct{}

Done returns a channel signaling when it is done

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

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

	// 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 verified flag will always be false.
	VerifyPeerCertificate func(cer *x509.Certificate, verified bool) 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

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

	LoggerFactory logging.LoggerFactory

	// ConnectTimeout is the timeout threshold for new connection handshakes
	// to complete (default is 30 seconds)
	ConnectTimeout *time.Duration

	// MTU is the length at which handshake messages will be fragmented to
	// fit within the maximum transmission unit (default is 1200 bytes)
	MTU 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 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 ExtendedMasterSecretType added in v1.5.2 

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 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(shutdownTimeout time.Duration) error

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

type PSKCallback added in v1.3.5 

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

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
dial-psk
listen
listen-psk
util
internal
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.
udp

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.