dtls13

README

go-dtls

go-dtls 是一个使用 Go 实现的 DTLS 1.3 库，协议行为以 RFC 9147 为准。模块导入路径为 github.com/puernya/go-dtls，包名为 dtls13。

当前实现完成了 RFC 9147、其继承的 TLS 1.3 强制语义，以及 RFC 9147 列出的全部 11 项直接规范性引用审计。本文记录 2026-07-27 当前源码的实现状态、测试证据和性能基线。

本项目仍处于活跃开发阶段。RFC 审计完成不等同于第三方合规认证；部署到生产环境前，应根据实际网络、证书体系和对端实现完成独立测试。

核心语义

DTLS 是不可靠报文协议，不是 TLS 字节流：

• Conn 有意不实现 net.Conn 或 net.PacketConn。
• 一次 WriteDatagram 发送一条 DTLS Application Data record；应用报文不会被内部拆分、排序或重传。
• 一次 ReadDatagram 消费一条认证后的 Application Data record；缓冲区过小时会丢弃余部，并通过 DatagramInfo.Truncated 报告。
• 默认情况下，超过当前路径 MTU 或 RFC record 上限的应用报文返回 ErrDatagramTooLarge，不会部分发送；IgnorePathMTU 可只跳过前一项检查。
• 握手消息仍按 RFC 9147 执行分片、ACK、丢包恢复和指数退避；这些可靠性机制不会改变应用数据的报文语义。
• Listener 从 UDP socket 接受经过认证的 DTLS association，并返回强类型 *dtls13.Conn。

环境要求

项目	要求
Go	最低 Go 1.26；当前审计环境为 Go 1.26.3 windows/amd64
Transport	udp、udp4 或 udp6；不接受 TCP
Windows race	仓库脚本需要 Zig 0.17 和可用的 CGO 工具链
wolfSSL 互通测试	可选；需要设置 WOLFSSL_ROOT 指向兼容的 wolfSSL 源码/构建目录

安装：

go get github.com/puernya/go-dtls

导入路径末段包含连字符，因此 Go 源码中使用声明的包名 dtls13：

import dtls13 "github.com/puernya/go-dtls"

快速开始

客户端

Dial 创建 UDP 连接并在返回前完成握手。下面的客户端验证服务端证书、发送一条报文并读取一条响应：

package main

import (
	"crypto/x509"
	"log"
	"os"
	"time"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	caPEM, err := os.ReadFile("ca.pem")
	if err != nil {
		log.Fatal(err)
	}
	roots := x509.NewCertPool()
	if !roots.AppendCertsFromPEM(caPEM) {
		log.Fatal("ca.pem does not contain a certificate")
	}

	conn, err := dtls13.Dial("udp", "127.0.0.1:4444", &dtls13.Config{
		RootCAs:    roots,
		ServerName: "server.example",
		NextProtos: []string{"example/1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	if err = conn.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
		log.Fatal(err)
	}
	if _, err = conn.WriteDatagram([]byte("ping")); err != nil {
		log.Fatal(err)
	}

	buffer := make([]byte, 1200)
	n, info, err := conn.ReadDatagram(buffer)
	if err != nil {
		log.Fatal(err)
	}
	if info.Truncated {
		log.Fatalf("response needs %d bytes", info.FullLength)
	}
	log.Printf("received %q from %s", buffer[:n], info.Source)
}

服务端

Listen 创建 UDP listener。Accept 在收到新 association 后返回 *Conn，应用可显式调用 Handshake，也可让首次 ReadDatagram 或 WriteDatagram 触发握手。

package main

import (
	"crypto/tls"
	"log"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	certificate, err := tls.LoadX509KeyPair("server.crt", "server.key")
	if err != nil {
		log.Fatal(err)
	}

	listener, err := dtls13.Listen("udp", ":4444", &dtls13.Config{
		Certificates: []tls.Certificate{certificate},
		NextProtos:   []string{"example/1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer listener.Close()

	for {
		conn, err := listener.Accept()
		if err != nil {
			log.Fatal(err)
		}
		go serve(conn)
	}
}

func serve(conn *dtls13.Conn) {
	defer conn.Close()
	if err := conn.Handshake(); err != nil {
		log.Printf("handshake: %v", err)
		return
	}

	buffer := make([]byte, 1200)
	n, info, err := conn.ReadDatagram(buffer)
	if err != nil {
		log.Printf("read: %v", err)
		return
	}
	if info.Truncated {
		log.Printf("discarded truncated datagram: need %d bytes", info.FullLength)
		return
	}
	if _, err = conn.WriteDatagram(buffer[:n]); err != nil {
		log.Printf("write: %v", err)
	}
}

常用 API

API	用途
Dial / DialWithDialer	创建 UDP 客户端连接并完成握手；DialWithDialer 可配置本地地址和拨号超时
Listen	创建并拥有一个 UDP listener
NewListener	在已有 net.PacketConn 上创建 DTLS listener；配置错误由 Accept 返回
Listener.Accept	接受一个新 association，返回 *Conn
Client / Server	在已有 connected net.Conn 上包装 DTLS 客户端或服务端；首次 I/O 前可显式握手
Handshake / HandshakeContext	显式执行一次握手；后续调用返回同一结果
ReadDatagram	读取一条认证报文，并返回来源、完整长度和截断状态
WriteDatagram	向 association 的认证对端发送一条报文
SetDeadline / SetReadDeadline / SetWriteDeadline	设置底层报文 I/O deadline
ConnectionState	获取版本、套件、ALPN、证书、恢复状态和当前 CID
Close	发送 close_notify、清除 traffic/resumption secrets 并关闭底层连接

报文大小与截断

应用应在写入前使用 PathMTU 和 RecordOverhead 估算当前最大 payload，并处理 PMTU 在连接生命周期内下降的情况：

maximum := conn.PathMTU() - conn.RecordOverhead()
if len(payload) > maximum {
	// 拆分属于应用协议职责；每个分片仍是一条独立 datagram。
}

即使预检查通过，路径状态仍可能在检查后变化，因此必须处理写入错误：

if _, err := conn.WriteDatagram(payload); errors.Is(err, dtls13.ErrDatagramTooLarge) {
	// 根据应用协议缩小或拆分 payload，然后作为新 datagram 重试。
}

需要由应用主动探测 PMTU 或明确依赖 IP 分片时，可以配置 IgnorePathMTU: true。此时 WriteDatagram 和 WriteEarlyData 跳过库内 PMTU payload 检查，把单个完整 DTLS record 直接交给底层 transport；握手、 ACK 和 post-handshake flight 仍按 PMTU 分片、重传和退避。该选项不会放宽 2^14 字节 record content 上限，底层仍可能分片、丢包或返回 ErrDatagramTooLarge，库不会降低 PMTU 或自动重发该应用 datagram。

ReadDatagram 的短缓冲不是流式读取。Truncated=true 时，该 record 的未读部分已经丢弃，下一次读取会返回下一条 record。

错误模型

错误	含义
*ConfigError	本地配置不合法，例如 transport、MTU、套件或资源上限无效
*ProtocolError	收到或生成了不符合协议状态/格式的内容
AlertError	对端返回 fatal TLS alert；可用 errors.As 获取 alert description 数值
ErrDatagramTooLarge	应用 datagram 超过当前 PMTU 或 record 上限；开启 IgnorePathMTU 后底层仍可能返回；可用 errors.Is 判断
ErrEarlyDataUnavailable	没有可用的 early-data ticket，或该连接不能发送 0-RTT
ErrEarlyDataRejected	握手完成，但对端因 HRR、重放或策略拒绝了已发送的 0-RTT
io.EOF	对端发送了合法 close_notify，读取方向已关闭

deadline、socket 关闭和底层 UDP 错误沿 Go net 错误模型返回；调用方不应依赖错误字符串。

高级能力

能力	API / 配置	说明
Session resumption	ClientSessionCache、NewLRUClientSessionCache	客户端缓存 NewSessionTicket；服务端由 SessionTicketKey 和 ticket 配置控制
0-RTT	WriteEarlyData、MaxEarlyData、EarlyDataReplayCache	仅恢复连接可用；调用方必须处理 ErrEarlyDataUnavailable 和 ErrEarlyDataRejected，且 early data 必须具备可重放语义
KeyUpdate	SendKeyUpdate(requestPeer)	可靠发送并在 ACK 后切换发送 epoch；接近 AEAD 使用上限时也会自动触发
CID	ConnectionID、GetConnectionID、SendNewConnectionIDs、RequestConnectionIDs、UseNextConnectionID	支持 RFC 9146 协商、动态更新和 Listener 路由；CID 认证不等于新网络路径已验证
握手内客户端认证	ClientAuth、ClientCAs、Certificates	使用 crypto/tls 的客户端证书策略
握手后客户端认证	PostHandshakeAuth、RequestClientCertificate	客户端先声明支持，服务端再发起 PHA
Exporter	ConnectionState().ExportKeyingMaterial	提供 RFC 8446 section 7.5、使用 DTLS dtls13 label 的导出材料

主要配置

Config 在 TLS 1.3 语义相同的字段上尽量沿用 crypto/tls.Config。配置可以复用，但首次使用后不得修改；需要派生配置时使用 Clone。

配置	默认值 / 行为
Certificates / GetCertificate	服务端证书；需要证书认证的服务端必须提供
RootCAs / ServerName	客户端服务端证书验证；Dial 未设置 ServerName 时使用目标主机名
ClientCAs / ClientAuth	服务端客户端证书验证策略
VerifyPeerCertificate	在标准证书处理后执行附加验证
InsecureSkipVerify	默认 false；生产环境不应依赖它跳过身份验证
NextProtos	ALPN 协议列表
CipherSuites	AES-128-GCM、AES-256-GCM、ChaCha20-Poly1305、AES-128-CCM
CurvePreferences	X25519、P-256
MTU	1200 字节 UDP payload；最小 256
IgnorePathMTU	默认 false；仅让 Application Data 跳过库内 PMTU 检查，握手不受影响
FlightInterval	1 秒初始握手重传间隔
MaxFlightInterval	60 秒指数退避上限
HandshakeTimeout	30 秒
ReplayWindow	每个 epoch 64 条 record
MaxHandshakeMessage	1 MiB，最大可配置到 2^24-1
MaxBufferedApplicationData	1 MiB
MaxBufferedApplicationDatagrams	1024 条
MaxPendingConnections	128 个 Listener session
MaxSessionQueueDatagrams	每个 Listener session 64 条
SessionTicketLifetime	24 小时，最大 7 天
MaxEarlyData	0，即默认关闭 0-RTT
MaxConnectionIDs	每个方向 8 个 CID

支持的 cipher suite：

常量	ID	状态
TLS_AES_128_GCM_SHA256	0x1301	支持
TLS_AES_256_GCM_SHA384	0x1302	支持
TLS_CHACHA20_POLY1305_SHA256	0x1303	支持
TLS_AES_128_CCM_SHA256	0x1304	支持
TLS_AES_128_CCM_8_SHA256	0x1305	显式禁用；通用库无法保证 RFC 9147 要求的部署级额外防伪措施

RFC 9147 完成度

章节覆盖

RFC 9147 章节	状态	实现摘要
section 1-2 引言和术语	不适用	按 RFC 2119/8174 解释规范关键字，无独立 wire 功能
section 3 设计目标	完成	丢包、乱序、重复、延迟、分片、反重放、动态 PMTU 和资源回收
section 4 Record Layer	完成	DTLSPlaintext、统一头、截断序号、epoch、AEAD、序号保护、anti-replay、CID demux 和使用上限
section 5 Handshake	完成	TLS 1.3 握手、HRR cookie、认证、分片重组、flight、ACK、重传、超时和同五元组新关联
section 6 Epochs	完成	epoch 0/1/2/3/4+、0-RTT、KeyUpdate 及旧 key 有界保留和清除
section 7 ACK	完成	content type 26、空 ACK、即时 ACK、部分 ACK、滑动窗口和 post-handshake 可靠 ACK
section 8 KeyUpdate	完成	ACK-gated 更新、重传、update_requested、旧 epoch 保留和极限处理
section 9 CID Update	完成	New/RequestConnectionId、动态路由、更新 ACK、资源上限和 prefix-free 校验
section 10 Application Data	完成	connected-datagram API、报文边界、无排序/重传、显式截断和 deadline
section 11 Security	完成	cookie 轮换、3 倍放大限制、anti-replay、AEAD limit、地址保持和有界状态
section 12 DTLS 1.2 differences	完成	所有适用差异已进入记录层、握手、epoch、ACK 和 CID 实现
section 13 DTLS 1.2 updates	不适用	本模块只实现 DTLS 1.3
section 14 IANA	不适用	使用已分配编号，本库不执行注册表操作

直接规范性引用

该表对应 RFC Editor 发布的 RFC 9147 XML 中全部 11 项 Normative References。下层协议由 Go 和操作系统实现，不表示本库重新实现 UDP/TCP/IP 栈。

规范	RFC 9147 中的用途	覆盖状态
RFC 8439	ChaCha20 序号保护的 counter、nonce 和 block function	完成
RFC 768	UDP transport	下层完成；库限制为 UDP，保持 datagram 边界
RFC 793	可靠传输背景和旧 epoch 的 MSL 参考	适用语义完成；本库不接受 TCP transport
RFC 1191	IPv4 PMTU discovery	下层交互完成；内部处理平台 MTU 错误，对外统一为 ErrDatagramTooLarge；应用可用 IgnorePathMTU 主动探测
RFC 2119	BCP 14 规范关键字	审计规则完成
RFC 4443	IPv6 ICMP Packet Too Big	下层交互完成；由 OS 处理 ICMPv6，库消费写入错误反馈
RFC 4821	Packetization Layer PMTU Discovery	完成；发送错误和连续黑洞超时触发退避与重新分片
RFC 6298	RTO 初值、指数退避和上限	完成；默认 1 秒、最大 60 秒，并使用符合 Karn 原则的 RTT 样本
RFC 8174	BCP 14 大小写限定	审计规则完成
RFC 9146	DTLS Connection ID	完成；协商、更新、路由、隔离和资源上限
RFC 8446	TLS 1.3 基础协议	完成；握手、认证、key schedule、PSK/0-RTT、KeyUpdate、PHA、exporter 和 alert

范围边界

以下项目不降低 RFC 9147 强制语义完成度，但使用者应明确其边界：

• 本模块只实现 DTLS 1.3，不提供 DTLS 1.2 回退。
• Heartbeat 的 record demux 已实现；完整 Heartbeat 协议由 RFC 6520 定义，不属于 RFC 9147 范围。
• 发送端采用一条 record 一个 UDP datagram 的合法模式，未暴露可选的多 record 聚合 API。
• 未暴露并行多个 NewSessionTicket 或 PHA 请求；RFC 允许但不要求这些并行能力。
• CID 可从新来源地址路由和认证 record，但不会自动更新回包地址；RFC 9147 不定义路径验证过程。
• wolfSSL 5.9.2 互通构建未启用 CID 和 0-RTT，因此这两项当前只有自互通与专项压力证据。

Benchmark

以下为 2026-07-27 的代表值，环境为 AMD Ryzen 7 7435H、Go 1.26.3、Windows/amd64。数值用于观察回归，不是跨机器性能保证。

场景	代表结果
完整证书握手和关闭 BenchmarkConnectionHandshakeLifecycle	约 642.9 us/op，111420 B/op，874 allocs/op
AES-128-GCM 1200 B seal	约 1.50-1.51 GB/s，1 alloc/op
AES-128-GCM 1200 B in-place round trip	约 862-954 MB/s，1 alloc/op
未认证 record 错误分类	约 12.4-13.7 ns/op，0 allocs/op
Extension marshal	约 316.5-358.0 ns/op，128 B/op，1 alloc/op
Extension ordered-view parse	约 69.8-80.1 ns/op，0 B/op，0 allocs/op
单 key_share caller-storage parse	约 33.5-35.0 ns/op，0 B/op，0 allocs/op
ClientHello marshal	约 436-519 ns/op，424 B/op，7 allocs/op
ServerHello marshal	约 72-91 ns/op，112 B/op，1 alloc/op
1200 B 单分片握手重组	约 0.47-0.60 us/op，1280 B/op，1 alloc/op
4 KiB / MTU 1200 protected flight 构造	约 3.00-3.26 us/op，5616 B/op，6 allocs/op
4 KiB / MTU 1200 plain flight 构造	约 2.15-2.58 us/op，5040 B/op，9 allocs/op

完整连接 benchmark 是性能验收的主门禁。当前完整连接对同期基线约快 2.2%，少 15 allocs/op；局部优化若只改善微基准但使完整连接退化，会被回退。

运行全部 benchmark：

go test -run '^$' -bench . -benchmem

单独复测完整连接与记录层：

go test -run '^$' -bench '^BenchmarkConnectionHandshakeLifecycle$' -benchmem -benchtime=2000x -cpu=1
go test -run '^$' -bench '^BenchmarkProtectedRecord(Seal|RoundTripInPlace)$' -benchmem -count=5

仓库还包含 cipher suite、ACK、record/parser、transcript、key schedule、KeyUpdate、握手消息、重组和 flight 构造等细分 benchmark。比较修改前后结果时，应固定 Go 版本、CPU、-cpu 和 -benchtime，交替运行多个样本，并同时观察 ns/op、B/op、allocs/op 与完整连接 profile。

验证

常规回归：

go test ./... -count=10 -timeout=10m
go vet ./...

Windows race：

.\tools\test-race.ps1

wolfSSL 双向 UDP 互通：

$env:WOLFSSL_ROOT = 'C:\path\to\wolfssl'
go test -run TestInteropWolfSSL -v -count=10

最近记录的验证结果：

• 全量测试、go vet 和 Windows race 于 2026-07-27 通过。
• 综合双向丢包、延迟、乱序和重复，以及 CH/SH/Finished/ACK/HRR 重传组合，连续 100 次通过。
• CID、KeyUpdate、恢复、0-RTT、exporter 和 post-handshake authentication 压力组合连续 100 次通过。
• parser/record fuzz 累计覆盖数百万输入，并包含四套 AEAD 的复制与原地解密差分。
• wolfSSL 5.9.2 双向互通覆盖 HRR、RSA-PSS 证书握手、Finished ACK、应用数据、AES-GCM 和 AES-128-CCM。

协议行为变更必须同步更新本文的完成度、验证证据、性能数据和第三方互通边界。

许可证

本项目以 GNU General Public License v3.0（GPL-3.0-only）发布。

Documentation

Overview

Package dtls13 implements Datagram Transport Layer Security 1.3 as defined by RFC 9147. It provides authenticated, encrypted datagrams over UDP and supports the TLS 1.3 handshake inherited from RFC 8446. The package does not implement DTLS 1.2 or protocol-version fallback.

Datagram semantics

DTLS preserves application message boundaries. A Conn is therefore not a net.Conn byte stream and intentionally implements neither net.Conn nor net.PacketConn. Applications use Conn.WriteDatagram and Conn.ReadDatagram instead.

Each call to WriteDatagram sends exactly one DTLS Application Data record. Application data is not fragmented, reordered, or retransmitted by this package. By default, a datagram that exceeds the current path MTU or the DTLS record limit is rejected with ErrDatagramTooLarge before any partial record is sent. Config.IgnorePathMTU skips the library's PMTU check for application data, but the record limit and transport errors still apply. Applications that need messages larger than the available payload must define their own fragmentation and recovery protocol.

Each successful call to ReadDatagram consumes exactly one authenticated Application Data record. If the destination is too small, the unread bytes are discarded and DatagramInfo.Truncated is true. DatagramInfo.FullLength reports the original length. Empty application datagrams are valid. Replay protection discards duplicate and stale records, but records may otherwise be delivered out of order because the underlying transport is unreliable.

Handshake and post-handshake messages have different reliability rules. The package fragments them to the configured MTU, acknowledges records, and retransmits unacknowledged flight data with bounded exponential backoff as required by RFC 9147. Those mechanisms do not make application data reliable.

Clients and servers

Dial and DialWithDialer create a connected UDP client and complete its handshake before returning. Listen owns a UDP socket and returns a Listener, whose Listener.Accept method yields one Conn per DTLS association. NewListener places the same association demultiplexer over an existing net.PacketConn.

Client and Server wrap an existing connected datagram net.Conn, usually a net.UDPConn. The transport must preserve datagram boundaries: a stream transport such as TCP is not valid. These constructors defer the handshake until Conn.Handshake, Conn.ReadDatagram, or Conn.WriteDatagram is first called. Closing a Conn closes its underlying transport.

A Config may be shared by multiple connections, but it must not be modified after first use. Use Config.Clone to derive an independent configuration. Conn methods synchronize protocol state; a reader and a writer may operate concurrently. Multiple ReadDatagram calls are serialized, as are multiple writes.

Authentication

Certificate and ALPN configuration follows the corresponding TLS 1.3 concepts in crypto/tls.Config. Clients normally set Config.RootCAs and Config.ServerName. Servers set Config.Certificates or Config.GetCertificate, and may configure Config.ClientAuth and Config.ClientCAs for client authentication.

Config.InsecureSkipVerify disables the built-in peer identity check and should not be enabled in production unless Config.VerifyPeerCertificate performs an equivalent check. Encryption without authentication does not prevent an active attacker from impersonating a peer.

Session resumption and 0-RTT

Set Config.ClientSessionCache to retain NewSessionTicket state and enable client-side session resumption. The built-in cache returned by NewLRUClientSessionCache is bounded and safe for concurrent use. Servers can share Config.SessionTicketKey when tickets must remain valid across server instances.

Conn.WriteEarlyData attempts one client 0-RTT datagram using a cached session. The server must configure Config.MaxEarlyData and an appropriate replay policy. Config.EarlyDataReplayCache controls replay admission; a nil cache selects a bounded process-wide cache. On an untrusted UDP listener, leave Config.AllowEarlyDataWithoutCookie false; accepting early data before return-routability validation increases amplification exposure.

Successful replay-cache admission reduces accidental or malicious reuse of a ticket identity within one cache domain, but it cannot give 0-RTT the same replay guarantees as 1-RTT data. Early data can be replayed across failures, cache domains, or server deployments. It must contain only operations that are safe to repeat. Callers must handle ErrEarlyDataUnavailable and ErrEarlyDataRejected and decide whether to retry after the handshake.

Connection IDs and network paths

The package implements DTLS Connection IDs from RFC 9146, including the RFC 9147 post-handshake update messages. Config.ConnectionID and Config.GetConnectionID configure local IDs; Conn.SendNewConnectionIDs, Conn.RequestConnectionIDs, and Conn.UseNextConnectionID manage updates. A Listener can use authenticated CIDs to route records whose source address has changed.

A CID authenticates a connection, not a network path. This package does not define or perform path validation and does not automatically change the address used for replies merely because a valid record arrived from a new address. Applications that support migration must provide a path-validation and rebinding policy appropriate to their protocol.

Post-handshake operations

Conn.SendKeyUpdate performs the ACK-gated DTLS 1.3 KeyUpdate procedure; the sending epoch changes only after the update record is acknowledged. The package also initiates KeyUpdate automatically before an AEAD usage limit is reached.

A client sets Config.PostHandshakeAuth to advertise post-handshake client authentication. A server whose Config.ClientAuth requests a certificate can then call Conn.RequestClientCertificate. Exporters are available after a completed handshake through ConnectionState.ExportKeyingMaterial.

Resource limits and errors

Config includes explicit bounds for handshake reassembly, queued application datagrams, Listener associations, per-association input, replay state, and Connection IDs. The defaults suit ordinary Internet-sized datagrams and certificate chains. Increase a limit only when the application also accepts the corresponding memory and denial-of-service cost.

Local configuration failures are reported as ConfigError, protocol and state-machine failures as ProtocolError, and fatal alerts received from a peer as AlertError. Datagram-size errors can be tested with errors.Is against ErrDatagramTooLarge. A valid peer close_notify causes ReadDatagram to return io.EOF. Network errors and deadlines follow the standard net package conventions. Applications should inspect errors with errors.Is and errors.As, not by matching error strings.

Index

• Constants
• Variables
• type AlertError
  • func (e AlertError) Error() string
• type ClientHelloInfo
• type ClientSessionCache
  • func NewLRUClientSessionCache(capacity int) ClientSessionCache
• type ClientSessionState
• type Config
  • func (c *Config) Clone() *Config
• type ConfigError
  • func (e *ConfigError) Error() string
• type Conn
  • func Client(conn net.Conn, config *Config) *Conn
  • func Dial(network, address string, config *Config) (*Conn, error)
  • func DialWithDialer(dialer *net.Dialer, network, address string, config *Config) (*Conn, error)
  • func Server(conn net.Conn, config *Config) *Conn
  • func (c *Conn) Close() error
  • func (c *Conn) ConnectionState() ConnectionState
  • func (c *Conn) Handshake() error
  • func (c *Conn) HandshakeContext(ctx context.Context) error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) PathMTU() int
  • func (c *Conn) ReadDatagram(p []byte) (int, DatagramInfo, error)
  • func (c *Conn) RecordOverhead() int
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) RequestClientCertificate(ctx context.Context) error
  • func (c *Conn) RequestConnectionIDs(count uint8) error
  • func (c *Conn) SendKeyUpdate(requestPeer bool) error
  • func (c *Conn) SendNewConnectionIDs(connectionIDs [][]byte, immediate bool) error
  • 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) UseNextConnectionID() error
  • func (c *Conn) WriteDatagram(p []byte) (int, error)
  • func (c *Conn) WriteEarlyData(p []byte) (int, error)
• type ConnectionState
  • func (s ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)
• type DatagramInfo
• type EarlyDataReplayCache
  • func NewLRUEarlyDataReplayCache(capacity int) EarlyDataReplayCache
• type Listener
  • func Listen(network, address string, config *Config) (*Listener, error)
  • func NewListener(inner net.PacketConn, config *Config) *Listener
  • func (l *Listener) Accept() (*Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
• type ProtocolError
  • func (e *ProtocolError) Error() string

Examples

• Conn.ReadDatagram
• Conn.WriteDatagram
• Conn.WriteEarlyData
• Dial
• Listen

Constants

const (
	// TLS_AES_128_GCM_SHA256 identifies the TLS_AES_128_GCM_SHA256 TLS 1.3
	// cipher suite.
	TLS_AES_128_GCM_SHA256 uint16 = 0x1301
	// TLS_AES_256_GCM_SHA384 identifies the TLS_AES_256_GCM_SHA384 TLS 1.3
	// cipher suite.
	TLS_AES_256_GCM_SHA384 uint16 = 0x1302
	// TLS_CHACHA20_POLY1305_SHA256 identifies the
	// TLS_CHACHA20_POLY1305_SHA256 TLS 1.3 cipher suite.
	TLS_CHACHA20_POLY1305_SHA256 uint16 = 0x1303
	// TLS_AES_128_CCM_SHA256 identifies the TLS_AES_128_CCM_SHA256 TLS 1.3
	// cipher suite.
	TLS_AES_128_CCM_SHA256 uint16 = 0x1304
	// TLS_AES_128_CCM_8_SHA256 identifies TLS_AES_128_CCM_8_SHA256. The value
	// is exported for protocol identification, but the suite is not supported
	// by this package and is rejected in Config.CipherSuites. RFC 9147 requires
	// additional deployment-level safeguards for its shortened authentication
	// tag that a general-purpose library cannot enforce.
	TLS_AES_128_CCM_8_SHA256 uint16 = 0x1305
)

const VersionDTLS13 uint16 = 0xfefc

VersionDTLS13 is the DTLS 1.3 version value carried in supported_versions.

Variables

var (
	// ErrDatagramTooLarge indicates that an application datagram exceeds the
	// current path MTU or the DTLS record size limit. A transport can still
	// return it when [Config.IgnorePathMTU] is enabled. [Conn.WriteDatagram] and
	// [Conn.WriteEarlyData] may wrap it in a net.OpError; use [errors.Is] to test
	// for it. No partial application record is sent when this error is returned.
	ErrDatagramTooLarge = errors.New("dtls13: datagram too large")
	// ErrEarlyDataUnavailable indicates that no usable PSK ticket with an
	// early-data allowance was available, the connection is not a client, or
	// WriteEarlyData was already attempted. The handshake may still have
	// completed successfully and 1-RTT data may still be sent.
	ErrEarlyDataUnavailable = errors.New("dtls13: early data unavailable")
	// ErrEarlyDataRejected indicates that the peer completed the handshake but
	// did not accept the queued 0-RTT record, for example because of a
	// HelloRetryRequest, replay detection, or server policy. The caller decides
	// whether the operation is safe to retry as 1-RTT data.
	ErrEarlyDataRejected = errors.New("dtls13: early data rejected")
)

Types

type AlertError

type AlertError uint8

AlertError reports a fatal TLS alert received from the peer. Its numeric value is the alert description assigned by TLS. Compare a known description with errors.Is, or use errors.As to obtain the value without depending on an error string.

func (AlertError) Error

func (e AlertError) Error() string

type ClientHelloInfo

type ClientHelloInfo struct {
	// ServerName is the SNI name requested by the client, or the empty string
	// when the client sent no server_name extension.
	ServerName string
	// SupportedProtos lists the ALPN protocols offered by the client, in client
	// preference order. The callback must not retain or modify this slice.
	SupportedProtos []string
	// Conn is the server connection processing the ClientHello. Its handshake is
	// not complete while GetCertificate is running.
	Conn *Conn
}

ClientHelloInfo contains information from a ClientHello for a Config.GetCertificate callback. Its fields must not be modified.

type ClientSessionCache

type ClientSessionCache interface {
	// Get returns the session associated with sessionKey. The returned state is
	// read-only and must not be modified.
	Get(sessionKey string) (*ClientSessionState, bool)
	// Put associates cs with sessionKey. A nil cs removes any existing entry.
	// The package does not modify cs after the call returns.
	Put(sessionKey string, cs *ClientSessionState)
}

ClientSessionCache stores opaque DTLS client sessions by a package-defined server cache key. Implementations must be safe for concurrent use. A client consumes a selected ticket when beginning a resumption attempt so that concurrent connections do not intentionally reuse the same identity.

func NewLRUClientSessionCache

func NewLRUClientSessionCache(capacity int) ClientSessionCache

NewLRUClientSessionCache returns a concurrency-safe, fixed-capacity client session cache. The least recently used entry is removed when the capacity is exceeded. State is cloned on insertion and retrieval so callers cannot mutate cached ticket secrets.

If capacity is less than one, a default capacity of 64 is used.

type ClientSessionState

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

ClientSessionState is opaque state for one resumable DTLS session. Values are created and consumed by this package through ClientSessionCache and must not be modified by applications or cache implementations.

type Config

type Config struct {
	// Rand provides cryptographically secure randomness for key exchange,
	// signatures, cookies, tickets, and protocol nonces. It must be safe for
	// concurrent use. If nil, crypto/rand.Reader is used.
	Rand io.Reader
	// Time returns the current time for certificate validation, ticket expiry,
	// replay policy, and protocol timers. It must be safe for concurrent use.
	// If nil, time.Now is used.
	Time func() time.Time

	// Certificates contains certificate chains to present to the peer. A
	// server uses the first certificate unless GetCertificate is set. A client
	// considers the first certificate when the server requests client
	// authentication and sends it when compatible. The leaf certificate must be
	// followed by any intermediates, as in tls.Certificate.
	Certificates []tls.Certificate
	// GetCertificate selects a server certificate after the ClientHello has
	// been parsed. It must return a non-nil certificate or an error. When set,
	// it takes precedence over Certificates. It is not used by clients. The
	// callback must be safe for concurrent use when Config is shared.
	GetCertificate func(*ClientHelloInfo) (*tls.Certificate, error)
	// RootCAs defines the roots used by a client to verify the server
	// certificate. If nil, the host's root CA set is used.
	RootCAs *x509.CertPool
	// ClientCAs defines the roots used by a server when ClientAuth requires
	// client-certificate verification. If nil, the host's root CA set is used.
	ClientCAs *x509.CertPool
	// ServerName is sent by clients as SNI and is used to verify the server
	// certificate hostname. Dial derives it from the target address when it is
	// empty; Client does not.
	ServerName string
	// InsecureSkipVerify disables built-in certificate-chain and hostname
	// verification. Certificate signatures within the DTLS handshake are still
	// checked. This should be used only for tests or together with
	// VerifyPeerCertificate that implements equivalent identity verification.
	InsecureSkipVerify bool
	// VerifyPeerCertificate, when non-nil, is called after normal certificate
	// parsing and verification. rawCerts contains the peer-provided DER chain.
	// verifiedChains contains the chains built by normal verification, or is nil
	// when built-in verification was skipped. Returning an error aborts the
	// handshake.
	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
	// ClientAuth controls a server's policy for client certificates during the
	// handshake and for RequestClientCertificate. The zero value is
	// tls.NoClientCert. It is ignored by clients.
	ClientAuth tls.ClientAuthType
	// PostHandshakeAuth makes a client advertise support for post-handshake
	// client authentication and permits it to answer CertificateRequest using
	// Certificates. It has no effect on server configurations.
	PostHandshakeAuth bool
	// NextProtos lists supported ALPN protocol names in preference order. The
	// server's order controls selection. If either peer provides no list, no
	// protocol is negotiated; otherwise the handshake fails when there is no
	// common protocol.
	NextProtos []string
	// CipherSuites lists supported TLS 1.3 cipher suites in preference order.
	// Empty selects AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305, then AES-128-CCM.
	// TLS_AES_128_CCM_8_SHA256 is intentionally not supported.
	CipherSuites []uint16
	// CurvePreferences contains the elliptic curves used for ephemeral key
	// exchange, in preference order. Empty selects X25519 followed by P-256;
	// those are the only currently supported groups.
	CurvePreferences []tls.CurveID

	// MTU is the initial maximum UDP payload, including DTLS record framing,
	// generated by Conn. Values below 256 are rejected. Zero selects 1200 bytes,
	// which avoids IP fragmentation on the Internet paths discussed by RFC 9147
	// section 4.1.1. The effective path MTU may decrease after write errors or
	// repeated handshake timeouts; see Conn.PathMTU.
	MTU int
	// IgnorePathMTU skips the library's current PMTU payload limit for
	// Application Data, including 0-RTT. The zero value is false. When enabled,
	// each application datagram is still limited to one DTLS record with at
	// most 2^14 bytes of content, but the complete record is handed directly to
	// the transport. The network may fragment or drop it, or the transport may
	// return [ErrDatagramTooLarge].
	//
	// This option does not change handshake or post-handshake flight
	// fragmentation, retransmission, or PMTU backoff.
	IgnorePathMTU bool
	// FlightInterval is the initial handshake and post-handshake retransmission
	// timeout. Zero selects one second.
	FlightInterval time.Duration
	// MaxFlightInterval caps exponential retransmission backoff. Zero selects
	// 60 seconds.
	MaxFlightInterval time.Duration
	// HandshakeTimeout bounds the complete handshake. Zero selects 30 seconds.
	// A shorter HandshakeContext deadline takes precedence.
	HandshakeTimeout time.Duration
	// ReplayWindow is the number of record sequence numbers tracked per epoch.
	// It must be between 1 and 64. Zero selects 64. Larger values accept more
	// reordering at the cost of retaining a wider anti-replay window.
	ReplayWindow int
	// MaxHandshakeMessage bounds memory allocated while reassembling one
	// handshake message. Zero selects 1 MiB. RFC 9147 permits larger messages,
	// so applications with unusually large certificate chains may raise it up
	// to the protocol limit of 2^24-1 bytes.
	MaxHandshakeMessage int
	// MaxBufferedHandshakeMessages bounds the number of incomplete handshake
	// messages retained across message sequence numbers. Zero selects 8.
	MaxBufferedHandshakeMessages int
	// MaxBufferedHandshakeBytes bounds the total bytes retained for incomplete
	// handshake reassembly. Zero selects four times MaxHandshakeMessage. It must
	// be at least MaxHandshakeMessage.
	MaxBufferedHandshakeBytes int
	// MaxBufferedApplicationData bounds decrypted application data waiting for
	// ReadDatagram, in bytes. Zero selects 1 MiB. Exceeding the limit terminates
	// the association instead of allowing unbounded memory growth.
	MaxBufferedApplicationData int
	// MaxBufferedApplicationDatagrams bounds complete application records
	// waiting for ReadDatagram, including zero-length records. Zero selects 1024.
	// Exceeding the limit terminates the association.
	MaxBufferedApplicationDatagrams int
	// MaxPendingConnections bounds active address-demultiplexed Listener
	// sessions, including sessions returned by Accept. Zero selects 128. New
	// unrecognized peers are ignored while this limit is full.
	MaxPendingConnections int
	// MaxSessionQueueDatagrams bounds unread UDP datagrams per Listener
	// session. Zero selects 64; excess datagrams are dropped.
	MaxSessionQueueDatagrams int

	// ClientSessionCache enables client-side session resumption. A cache may be
	// shared by concurrent clients and therefore must be safe for concurrent use.
	ClientSessionCache ClientSessionCache
	// SessionTicketsDisabled disables server NewSessionTicket messages and
	// client ticket use. It also disables session resumption and 0-RTT.
	SessionTicketsDisabled bool
	// SessionTicketKey authenticates and encrypts server ticket state. Servers
	// sharing resumable sessions must use the same key. A zero key is replaced
	// with random key material when the configuration is first used.
	SessionTicketKey [32]byte
	// SessionTicketLifetime controls ticket validity. Zero selects 24 hours;
	// values from one second through seven days are accepted, matching RFC 8446.
	SessionTicketLifetime time.Duration
	// MaxEarlyData advertises and permits at most this many 0-RTT application
	// bytes per resumed connection. Zero disables early data. It does not by
	// itself make early data replay-safe; see EarlyDataReplayCache.
	MaxEarlyData uint32
	// EarlyDataReplayCache is shared by server connections to prevent reuse of
	// a PSK identity for 0-RTT. It must be safe for concurrent use. Nil uses a
	// bounded process-wide cache. Deployments with more than one process must
	// provide a cache whose replay domain covers every server that shares ticket
	// keys and accepts 0-RTT.
	EarlyDataReplayCache EarlyDataReplayCache
	// AllowEarlyDataWithoutCookie permits a server to accept 0-RTT on the
	// initial address before a cookie exchange. Keep it false on untrusted UDP
	// listeners: accepting application bytes before return-routability validation
	// increases amplification exposure. A false value causes early data to fall
	// back to a 1-RTT handshake through HelloRetryRequest.
	AllowEarlyDataWithoutCookie bool
	// ConnectionID is the CID that the peer places in protected records sent
	// to this endpoint. A non-nil empty slice negotiates support without
	// requesting a CID in this direction. Clients with nil ConnectionID offer
	// an empty CID by default, as recommended by RFC 9147 section 5.1.
	ConnectionID []byte
	// DisableConnectionID suppresses the client's recommended empty-CID offer
	// when ConnectionID is nil. It has no effect when ConnectionID is non-nil.
	DisableConnectionID bool
	// GetConnectionID optionally creates a local CID for each accepted Listener
	// session and in response to RequestConnectionId. It overrides ConnectionID
	// for a newly accepted Listener session. Returned IDs must be at most 255
	// bytes and must be unique and prefix-free among active sessions. The
	// callback may be invoked concurrently for different connections.
	GetConnectionID func() ([]byte, error)
	// MaxConnectionIDs bounds the number of local or peer-provided CIDs kept
	// for one connection. It must be between 1 and 255. Zero selects 8.
	MaxConnectionIDs int
	// contains filtered or unexported fields
}

Config configures a DTLS client or server. Fields that represent TLS 1.3 concepts follow crypto/tls.Config where practical.

A Config may be reused by multiple connections. It must not be modified after it has been passed to a DTLS function. Call Config.Clone before changing a configuration that is already in use.

func (*Config) Clone

func (c *Config) Clone() *Config

Clone returns a shallow clone of c whose slice-valued configuration fields have independent backing arrays. It is safe to clone a Config that is not being concurrently modified. Clone returns nil when c is nil.

Callback values, certificate internals, certificate pools, session caches, and the time and randomness sources are shared with c.

type ConfigError

type ConfigError struct {
	// Reason describes the rejected setting or limit.
	Reason string
}

ConfigError reports an invalid local configuration or an operation that exceeds a configured resource limit. Use errors.As to inspect the Reason.

func (*ConfigError) Error

func (e *ConfigError) Error() string

type Conn

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

Conn represents one DTLS association over a connected datagram transport. It exposes unreliable, message-oriented I/O and intentionally implements neither net.Conn nor net.PacketConn.

Unless Dial completed it already, the first call to Handshake, ReadDatagram, WriteDatagram, or another operation that requires traffic keys performs the handshake. Conn methods synchronize access to protocol state; reads and writes may run concurrently. Concurrent reads are serialized, as are concurrent writes.

func Client

func Client(conn net.Conn, config *Config) *Conn

Client returns a client-side DTLS association over conn. The underlying connection must be a connected datagram transport that preserves one write as one datagram, normally a *net.UDPConn; a stream connection is invalid.

Client does not perform network I/O. The first operation that needs traffic keys performs the handshake. Close closes conn. A nil config selects default settings, but a client that verifies certificates usually needs RootCAs and ServerName.

func Dial

func Dial(network, address string, config *Config) (*Conn, error)

Dial connects to address on a UDP network and performs a client handshake. Network must be "udp", "udp4", or "udp6". If Config.ServerName is empty, Dial derives it from the host portion of address. The returned Conn owns the underlying socket and must be closed by the caller.

Example

package main

import (
	"crypto/x509"
	"log"
	"os"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	rootPEM, err := os.ReadFile("ca.pem")
	if err != nil {
		log.Fatal(err)
	}
	roots := x509.NewCertPool()
	if ok := roots.AppendCertsFromPEM(rootPEM); !ok {
		log.Fatal("invalid root certificate")
	}

	conn, err := dtls13.Dial("udp", "dtls.example:4433", &dtls13.Config{
		RootCAs:    roots,
		ServerName: "dtls.example",
		NextProtos: []string{"example/1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	if _, err := conn.WriteDatagram([]byte("ping")); err != nil {
		log.Fatal(err)
	}
}

func DialWithDialer

func DialWithDialer(dialer *net.Dialer, network, address string, config *Config) (*Conn, error)

DialWithDialer is like Dial but uses dialer to create the connected UDP transport. A nil dialer is equivalent to a zero net.Dialer. A positive dialer Timeout also bounds the DTLS handshake; Config.HandshakeTimeout still applies when it is shorter.

func Server

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

Server returns a server-side DTLS association over conn. The underlying connection must be a connected datagram transport that preserves one write as one datagram. Server defers the handshake until the first operation that needs traffic keys. Close closes conn.

func (*Conn) Close

func (c *Conn) Close() error

Close sends close_notify when application sending keys are available, clears retained traffic, resumption, and exporter secrets, stops background protocol work, and closes the underlying transport. It does not wait for the peer to acknowledge close_notify.

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() ConnectionState

ConnectionState returns a snapshot of the current negotiated state. Before handshake completion its fields have zero values. Post-handshake client authentication and Connection ID changes are reflected in later snapshots.

func (*Conn) Handshake

func (c *Conn) Handshake() error

Handshake performs the DTLS handshake if it has not already run. Subsequent calls return the result of the first handshake attempt.

func (*Conn) HandshakeContext

func (c *Conn) HandshakeContext(ctx context.Context) error

HandshakeContext performs the DTLS handshake if it has not already run. The handshake is bounded by the earlier of ctx's deadline and Config.HandshakeTimeout. Canceling ctx interrupts transport I/O.

The first call controls the handshake and all later calls return its result; a canceled or failed handshake is not retried. The context must be non-nil.

func (*Conn) LocalAddr

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

LocalAddr returns the local network address of the underlying transport.

func (*Conn) PathMTU

func (c *Conn) PathMTU() int

PathMTU returns the current maximum transport datagram size used by the connection, including DTLS record framing. It starts at Config.MTU and can decrease in response to path-MTU write errors or repeated handshake timeouts. It returns zero before an effective configuration is available.

For an established connection, PathMTU()-RecordOverhead() is the current upper bound for an application datagram, subject also to the DTLS 2^14-byte record-content limit. The path can change after this check, so callers must still handle ErrDatagramTooLarge from Conn.WriteDatagram. Config.IgnorePathMTU makes application writes ignore this estimate; handshake traffic continues to use it.

func (*Conn) ReadDatagram

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

ReadDatagram reads and consumes one authenticated DTLS Application Data record. It performs the handshake first if necessary. The returned n is the number of plaintext bytes copied into p.

If p is too small, the unread remainder is discarded, DatagramInfo.FullLength reports the original length, and DatagramInfo.Truncated is true. A subsequent call reads the next record, not the remainder. Empty records are returned with n and FullLength both zero. A peer close_notify is returned as io.EOF after all earlier deliverable records have been consumed.

Example

package main

import (
	"fmt"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	read := func(conn *dtls13.Conn) ([]byte, error) {
		buffer := make([]byte, 1200)
		n, info, err := conn.ReadDatagram(buffer)
		if err != nil {
			return nil, err
		}
		if info.Truncated {
			// The rest of this datagram has already been discarded.
			return nil, fmt.Errorf("datagram needs %d bytes", info.FullLength)
		}
		return append([]byte(nil), buffer[:n]...), nil
	}

	_ = read
}

func (*Conn) RecordOverhead

func (c *Conn) RecordOverhead() int

RecordOverhead returns the number of bytes added around one application datagram in the current sending epoch, including record framing, the inner content type, and the AEAD tag. Before handshake keys exist it returns the plaintext record-header size and must not be used to size application data.

func (*Conn) RemoteAddr

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

RemoteAddr returns the destination address of the connected underlying transport. It is not automatically rebound when a valid CID record arrives from a different source address.

func (*Conn) RequestClientCertificate

func (c *Conn) RequestClientCertificate(ctx context.Context) error

RequestClientCertificate starts post-handshake client authentication and waits until the client's response has been received and verified. It is a server-only operation and performs the initial handshake first if necessary.

The client must have advertised Config.PostHandshakeAuth. The server's Config.ClientAuth must request or require a certificate, and ClientCAs and VerifyPeerCertificate are applied according to that policy. At most one post-handshake authentication exchange may be active on a connection.

Canceling ctx stops this call from waiting but does not retract a CertificateRequest that is already on the wire; the protocol exchange may continue in the background. A nil context is treated as context.Background.

func (*Conn) RequestConnectionIDs

func (c *Conn) RequestConnectionIDs(count uint8) error

RequestConnectionIDs reliably asks the peer to advertise up to count spare Connection IDs. It is valid only when a non-empty CID is active for records sent to the peer. A new request cannot be sent until the preceding request has been acknowledged and fulfilled.

The peer controls how many IDs it returns, subject to its Config.MaxConnectionIDs and Config.GetConnectionID policy.

func (*Conn) SendKeyUpdate

func (c *Conn) SendKeyUpdate(requestPeer bool) error

SendKeyUpdate reliably sends a post-handshake KeyUpdate. Application writes continue with the old sending epoch until the KeyUpdate record is acknowledged, as required by RFC 9147 section 8. If requestPeer is true, the peer is asked to update its sending keys as well.

Only one locally initiated KeyUpdate may await acknowledgement at a time. The package also initiates updates automatically before the negotiated AEAD usage limit is reached.

func (*Conn) SendNewConnectionIDs

func (c *Conn) SendNewConnectionIDs(connectionIDs [][]byte, immediate bool) error

SendNewConnectionIDs reliably advertises new local Connection IDs to the peer. Each ID is a value the peer may place in records sent to this endpoint. IDs must be at most 255 bytes and, together with existing local IDs, unique and prefix-free. Their total number is bounded by Config.MaxConnectionIDs.

When immediate is true, connectionIDs must be non-empty and the peer is instructed to switch immediately to one of the supplied IDs. Otherwise the IDs become spares. Only one locally initiated NewConnectionId flight may await acknowledgement at a time. The method fails if non-empty Connection IDs and local CID updates were not negotiated.

func (*Conn) SetDeadline

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

SetDeadline sets both read and write deadlines on the underlying transport. A zero value disables the deadlines. The deadline applies to currently blocked and future I/O, following net.Conn semantics. An initial handshake temporarily installs its own deadline and clears transport deadlines when it finishes.

func (*Conn) SetReadDeadline

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

SetReadDeadline sets the deadline for future and currently blocked reads from the underlying transport. A zero value disables the deadline.

func (*Conn) SetWriteDeadline

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

SetWriteDeadline sets the deadline for future and currently blocked writes to the underlying transport. A zero value disables the deadline.

func (*Conn) UseNextConnectionID

func (c *Conn) UseNextConnectionID() error

UseNextConnectionID switches outgoing protected records to the next spare CID provided by the peer. It returns an error if no spare CID is available.

Switching a CID changes record routing but does not validate, select, or rebind a network path. Applications implementing migration need a separate path-validation policy.

func (*Conn) WriteDatagram

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

WriteDatagram sends p as exactly one DTLS Application Data record to the association's authenticated peer. It performs the handshake first if necessary. Application data is not internally fragmented, retransmitted, or reordered. A nil or empty p sends a valid empty application datagram.

By default, if p exceeds the current path MTU or the DTLS record-content limit, WriteDatagram returns an error matching ErrDatagramTooLarge and n == 0, without a partial record on the wire. Config.IgnorePathMTU skips the library's PMTU check but not the record-content limit. The transport may still reject the complete record with ErrDatagramTooLarge. Otherwise n is len(p) if the complete record was handed to the underlying transport.

Example

package main

import (
	"errors"
	"fmt"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	send := func(conn *dtls13.Conn, payload []byte) error {
		if err := conn.Handshake(); err != nil {
			return err
		}
		maximum := conn.PathMTU() - conn.RecordOverhead()
		if len(payload) > maximum {
			return fmt.Errorf("payload is %d bytes; current maximum is %d", len(payload), maximum)
		}

		_, err := conn.WriteDatagram(payload)
		if errors.Is(err, dtls13.ErrDatagramTooLarge) {
			// The path MTU can decrease after the check above. Fragmentation and
			// retry policy belong to the application protocol.
			return fmt.Errorf("resize datagram: %w", err)
		}
		return err
	}

	_ = send
}

func (*Conn) WriteEarlyData

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

WriteEarlyData attempts to send p as one client 0-RTT Application Data record and completes the handshake. It can be called at most once and only on a client created with a usable cached session whose ticket permits early data. A nil or empty p is a no-op.

The method returns ErrEarlyDataUnavailable when no eligible early-data session exists, and ErrEarlyDataRejected when the record was sent but the server completed the handshake without accepting it. In both cases the caller may use the established connection for 1-RTT data. Retrying p is an application decision because 0-RTT data is replayable. Oversized data returns ErrDatagramTooLarge without a partial record. Config.IgnorePathMTU skips the library's PMTU check but not the DTLS record-content or ticket limits; the transport may still reject the complete record as too large.

Example

package main

import (
	"errors"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	sendReplaySafe := func(conn *dtls13.Conn, payload []byte) error {
		_, err := conn.WriteEarlyData(payload)
		switch {
		case err == nil:
			return nil
		case errors.Is(err, dtls13.ErrEarlyDataUnavailable),
			errors.Is(err, dtls13.ErrEarlyDataRejected):
			// Retry only because this application operation is safe to repeat.
			_, err = conn.WriteDatagram(payload)
			return err
		default:
			return err
		}
	}

	_ = sendReplaySafe
}

type ConnectionState

type ConnectionState struct {
	// Version is the negotiated DTLS version. It is VersionDTLS13 after a
	// successful handshake.
	Version uint16
	// HandshakeComplete is true after the initial handshake has completed and
	// installed application traffic keys.
	HandshakeComplete bool
	// DidResume is true when the connection used a PSK from a session ticket
	// instead of performing a full certificate handshake.
	DidResume bool
	// CipherSuite is the negotiated TLS 1.3 cipher-suite identifier.
	CipherSuite uint16
	// NegotiatedProtocol is the ALPN protocol selected by the server, or the
	// empty string when ALPN was not negotiated.
	NegotiatedProtocol string
	// ServerName is the name sent by a client and used for certificate hostname
	// verification when built-in verification is enabled. It is empty in
	// server-side state.
	ServerName string
	// PeerCertificates contains the certificate chain presented by the peer,
	// with the leaf first. It can be empty for an authenticated resumed session
	// or when a server did not request a client certificate.
	PeerCertificates []*x509.Certificate
	// VerifiedChains contains the chains built during certificate verification.
	// It is nil when built-in verification was skipped or the peer did not send
	// a certificate.
	VerifiedChains [][]*x509.Certificate
	// LocalConnectionID is the CID the peer currently uses when sending
	// protected records to this endpoint. It is empty when no non-empty CID is
	// active in that direction.
	LocalConnectionID []byte
	// PeerConnectionID is the CID this endpoint currently places in protected
	// records sent to the peer. It is empty when no non-empty CID is active in
	// that direction.
	PeerConnectionID []byte
	// contains filtered or unexported fields
}

ConnectionState records negotiated parameters and authenticated peer identity for a DTLS association. A zero value describes a connection whose handshake has not completed.

The certificate slices refer to immutable certificate objects owned by the connection and must not be modified. Connection ID slices returned by Conn.ConnectionState are copies.

func (ConnectionState) ExportKeyingMaterial

func (s ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)

ExportKeyingMaterial returns exporter output for the completed connection, following RFC 8446 section 7.5 with the DTLS 1.3 label prefix required by RFC 9147. A nil and an empty context are equivalent.

The label is application-defined and must fit the TLS HKDF label encoding. The maximum output is 255 times the negotiated hash length. The method returns an error before handshake completion, after the connection's secrets have been cleared, or for an invalid label or length.

type DatagramInfo

type DatagramInfo struct {
	// Source is the network address from which the authenticated record was
	// received. It is informational: Connection IDs do not by themselves
	// validate a changed network path or alter the address used for replies.
	Source net.Addr
	// FullLength is the length of the complete plaintext datagram before it was
	// copied into the caller's buffer.
	FullLength int
	// Truncated reports whether the caller's buffer was shorter than FullLength.
	// The unread remainder has already been discarded.
	Truncated bool
}

DatagramInfo describes one authenticated Application Data record consumed by Conn.ReadDatagram.

type EarlyDataReplayCache

type EarlyDataReplayCache interface {
	// CheckAndStore atomically admits identity until expires. It returns true
	// only when the identity was not already live and the cache retained the new
	// entry for its validity period within the cache's replay domain. It must
	// fail closed by returning false when it cannot store the entry.
	CheckAndStore(identity string, expires time.Time) bool
}

EarlyDataReplayCache controls server acceptance of PSK identities for 0-RTT. Implementations must be safe for concurrent use and should share a replay domain with every server process that shares SessionTicketKey and accepts early data.

A replay cache is a required mitigation, not a guarantee that early data cannot be replayed. Applications must still give 0-RTT operations idempotent or otherwise replay-safe semantics.

func NewLRUEarlyDataReplayCache

func NewLRUEarlyDataReplayCache(capacity int) EarlyDataReplayCache

NewLRUEarlyDataReplayCache creates a bounded, concurrency-safe in-process 0-RTT replay cache. Expired entries are removed as new identities are checked. Live entries are never evicted to make room: a full cache fails closed and rejects new early data until entries expire.

A non-positive capacity is rejected by returning nil. The cache covers only one process; distributed servers sharing ticket keys need a replay cache with a correspondingly shared consistency domain.

type Listener

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

Listener demultiplexes DTLS associations from one packet transport. It intentionally does not implement net.Listener because Conn exposes a connected datagram API rather than a byte stream.

Accept returns a Conn after receiving an initial datagram for a new peer; the DTLS handshake and peer authentication occur when Handshake or the first datagram I/O method is called. Listener bounds pending state and per-peer queues according to Config.

func Listen

func Listen(network, address string, config *Config) (*Listener, error)

Listen creates and owns a UDP socket on address, then returns a DTLS association listener. Network must be "udp", "udp4", or "udp6". A nil config selects defaults. Close releases the socket and all associations demultiplexed from it.

Example

package main

import (
	"crypto/tls"
	"log"

	dtls13 "github.com/puernya/go-dtls"
)

func main() {
	certificate, err := tls.LoadX509KeyPair("server.crt", "server.key")
	if err != nil {
		log.Fatal(err)
	}

	listener, err := dtls13.Listen("udp", ":4433", &dtls13.Config{
		Certificates: []tls.Certificate{certificate},
		NextProtos:   []string{"example/1"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer listener.Close()

	for {
		conn, err := listener.Accept()
		if err != nil {
			log.Printf("accept: %v", err)
			return
		}
		go func() {
			defer conn.Close()
			if err := conn.Handshake(); err != nil {
				log.Printf("DTLS handshake: %v", err)
				return
			}
			buffer := make([]byte, 1200)
			n, info, err := conn.ReadDatagram(buffer)
			if err != nil {
				log.Printf("read datagram: %v", err)
				return
			}
			if info.Truncated {
				log.Printf("discarded %d-byte datagram", info.FullLength)
				return
			}
			if _, err := conn.WriteDatagram(buffer[:n]); err != nil {
				log.Printf("write datagram: %v", err)
			}
		}()
	}
}

func NewListener

func NewListener(inner net.PacketConn, config *Config) *Listener

NewListener creates a DTLS association listener over inner. Ownership of inner is transferred to the Listener; Close closes it. inner must preserve datagram boundaries and provide source addresses, normally by being a UDP net.PacketConn.

NewListener cannot return an error for compatibility with construction over an existing transport. A nil transport and configuration initialization errors are retained and returned by Accept.

func (*Listener) Accept

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

Accept waits for the next candidate DTLS association and returns it as a server-side Conn. The returned connection has not necessarily completed its handshake; call Conn.Handshake to authenticate it before handing it to code that assumes an authenticated peer. Closing the returned Conn removes its association state from the Listener.

Accept returns a retained NewListener configuration error, the underlying packet read error, or net.ErrClosed after the Listener is closed.

func (*Listener) Addr

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

Addr returns the packet transport's local network address. It returns nil when the Listener has no underlying transport.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the packet transport, unblocks Accept, and closes all associations owned by the Listener. Calls blocked in Accept return net.ErrClosed unless an earlier packet-read error is available.

type ProtocolError

type ProtocolError struct {
	// Reason describes the protocol or state-machine violation.
	Reason string
}

ProtocolError reports malformed protocol data or an operation that is not valid in the connection's current DTLS state. When caused by authenticated peer input, the connection sends the corresponding fatal alert when possible. Use errors.As to inspect the Reason.

func (*ProtocolError) Error

func (e *ProtocolError) Error() string