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:

go run examples/listen/psk/main.go -dtls12
go run examples/dial/psk/main.go -dtls12

OpenSSL

Run the Pion example with -dtls12 when using these OpenSSL DTLS 1.2 commands.

  // Use with examples/dial/psk/main.go -dtls12
  openssl s_server -dtls1_2 -accept 4444 -nocert -psk abc123 -cipher PSK-AES128-CCM8

  // Use with examples/listen/psk/main.go -dtls12
  openssl s_client -dtls1_2 -connect 127.0.0.1:4444 -psk abc123 -cipher PSK-AES128-CCM8

Community

Pion has an active community on the Discord.

Follow the Pion Bluesky or Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at [email protected]

Contributing

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

Funding

The DTLS 1.3 implementation in this project is funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429. Additional funding is made available by the Swiss State Secretariat for Education, Research and Innovation (SERI). Learn more on the NLnet project page.

License

MIT License - see LICENSE for full text