Pion DTLS

A Go implementation of DTLS

Native DTLS 1.2 and DTLS 1.3 implementation in the Go programming language.

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

RFCs

Implemented

• RFC 6347: Datagram Transport Layer Security Version 1.2
• RFC 9146: Connection Identifier for DTLS 1.2
• RFC 9147: The Datagram Transport Layer Security (DTLS) Protocol Version 1.3
• RFC 9849: TLS Encrypted Client Hello
• RFC 9853: Return Routability Check for DTLS 1.2 and 1.3
• RFC 5705: Keying Material Exporters for Transport Layer Security (TLS)
• RFC 7627: Transport Layer Security (TLS) - Session Hash and Extended Master Secret Extension
• RFC 7301: Transport Layer Security (TLS) - Application-Layer Protocol Negotiation Extension

Features

Pion DTLS supports DTLS 1.2 and DTLS 1.3. We welcome contributions and bug fixes.

Current features

• DTLS 1.2 and DTLS 1.3 client/server
• Key Exchange via ECDHE(curve25519, nistp256, nistp384) and PSK
• DTLS 1.3 external PSK with psk_ke and psk_dhe_ke, supporting SHA-256 and SHA-384
• DTLS 1.3 offers multiple PSK identities per handshake for server selection
• Packet loss and re-ordering is handled during handshaking
• Key export (RFC 5705)
• DTLS 1.2 and DTLS 1.3 connection state serialization and restoration with Resume
• DTLS 1.3 session ticket resumption and optional 0-RTT early data
• DTLS 1.3 Encrypted Client Hello (ECH), configured with WithECH (RFC 9849)
• Extended Master Secret extension (RFC 7627)
• ALPN extension (RFC 7301)
• Connection IDs (CIDs) for DTLS 1.2 and DTLS 1.3, including listener routing across peer address changes
• DTLS 1.3 post-handshake CID updates and spare CIDs for path migration
• Return Routability Check (RRC) for DTLS 1.2 and DTLS 1.3 (RFC 9853)
• DTLS 1.3 local path probing and migration with Conn.AddPath, Path.Probe, and Path.Switch
• DTLS 1.3 traffic-key updates with Conn.UpdateKeys

Supported ciphers

DTLS 1.3: Certificate & PSK

• TLS_AES_128_GCM_SHA256 (RFC 8446)
• TLS_AES_256_GCM_SHA384 (RFC 8446)
• TLS_CHACHA20_POLY1305_SHA256 (RFC 8446)

DTLS 1.2: 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)
• TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 (RFC 7905)
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (RFC 7905)

DTLS 1.2: 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)
• TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 (RFC 7905)

DTLS 1.2: ECDHE & PSK

• TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 (RFC 5489)
• TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 (RFC 7905)

Excluded Features

• DTLS 1.0
• Renegotiation
• Compression

Pion DTLS

The library enables DTLS 1.2 and DTLS 1.3 by default, preferring DTLS 1.3. Use WithMaxVersion(protocol.Version1_2) to restrict a connection to DTLS 1.2, or WithMinVersion(protocol.Version1_3) to require DTLS 1.3.

For a DTLS server that listens on 127.0.0.1:4444

go run examples/listen/selfsign/main.go

For a DTLS 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

DTLS 1.3 resumption and early data

DTLS 1.3 supports session ticket resumption with optional 0-RTT early data. Resumption only allows psk_dhe_ke (PSK with ephemeral ECDHE).

The resumption example demonstrate a certificate-authenticated first connection, encrypted session storage, and subsequent connections with resumption and optional early data. See its README for run instructions and the session store's single-use Claim requirement for 0-RTT.

The State/Resume API also supports restoring established DTLS 1.3 connections without a new handshake. See Resume.

Using with PSK

DTLS 1.3 supports external PSKs with psk_ke (PSK-only) and psk_dhe_ke (PSK with ephemeral ECDHE), using SHA-256 or SHA-384. Clients can offer multiple PSK identities per handshake for the server to select from.

The PSK examples use DTLS 1.3 by default, with TLS_AES_128_GCM_SHA256.

Pion DTLS

go run examples/listen/psk/main.go

go run examples/dial/psk/main.go

To use DTLS 1.2 with TLS_PSK_WITH_AES_128_CCM_8, pass -dtls12 to both: