A cross-platform DTLS library for .NET that, like the BCL, uses the host operating system's cryptography. It supports DTLS 1.0, 1.2, and 1.3 with a modern, allocation-conscious (Span<T>) datagram API.
Status: actively developed and CI-green on Linux, Windows, and macOS. Working and verified end to end: the managed DTLS 1.3 engine (PSK, certificate, raw-public-key, mutual auth); the managed DTLS 1.2 engine (certificate, PSK, ECDHE-PSK, raw-public-key, mutual auth) used as the universal fallback where no native stack exists; the native Schannel (Windows), OpenSSL (Linux), and Network.framework (macOS) DTLS 1.2 backends, with the deprecated Secure Transport DTLS 1.0 stack as a fallback. The managed 1.2 engine is interop-tested against both OpenSSL and Schannel in CI (both directions), and the library negotiates a DTLS 1.3 → 1.2 downgrade automatically. See the documentation for details.
No native OS DTLS stack supports DTLS 1.3 yet (OpenSSL, Schannel, and Apple all cap at DTLS 1.2). To deliver 1.3 everywhere and stay NativeAOT-compatible, this library uses a hybrid design:
| DTLS version | Engine | Crypto provider |
|---|---|---|
| 1.0, 1.2 | Native OS stack (P/Invoke), or the managed C# engine where no native stack exists (iOS, Android) | OpenSSL (Linux) · Schannel (Windows) · Network.framework / Secure Transport (macOS) · BCL (managed fallback) |
| 1.3 | Managed C# | BCL System.Security.Cryptography (delegates to OpenSSL / CNG / Apple) |
Delegating the legacy CBC-era 1.0/1.2 handshakes to hardened native stacks avoids hand-rolling the most dangerous (timing/padding-oracle prone) crypto, while the clean AEAD-only 1.3 path — and the AEAD-only managed 1.2 fallback for platforms without a native stack — is implemented in managed, AOT-friendly code.
- DTLS 1.3 (managed; client and server) with PSK, X.509 certificate (ECDSA / RSA-PSS), Raw Public Key (RFC 7250), and mutual authentication.
- Managed DTLS 1.2 engine (client and server) — the universal fallback where no native stack exists (iOS, Android) — with certificate (ECDSA / RSA-PKCS#1), PSK and forward-secret ECDHE-PSK, Raw Public Key, and mutual authentication, plus
extended_master_secret(RFC 7627) and the stateless HelloVerifyRequest cookie. Interop-tested in CI against OpenSSL and Schannel in both directions. - Automatic DTLS 1.3 → 1.2 downgrade: at the default version range the client offers both and completes on whichever the peer selects, over the same transport.
- Native DTLS 1.2 backends — Schannel (Windows), OpenSSL (Linux), and Network.framework (macOS) — preferred where present; the deprecated Secure Transport stack provides a DTLS 1.0 fallback on macOS.
- AEAD cipher suites: AES-128-GCM and AES-256-GCM (all TFMs), plus AES-128-CCM and AES-128-CCM-8 (net8+; unavailable on iOS, where AES-GCM remains the default). Selectable via
DtlsOptions.CipherSuites. (ChaCha20-Poly1305 is not offered: the BCL has no raw ChaCha20 for DTLS 1.3 sequence-number encryption.) - Modern, allocation-conscious
Span<T>API; transport-agnostic with a built-in UDPSocketadapter and an in-memory loopback transport. - Targets netstandard2.0, netstandard2.1, net8.0, net9.0, net10.0 (plus opt-in
net10.0-android/net10.0-ios); NativeAOT-compatible on net10.netstandard2.0(for .NET Framework 4.6.1+, Unity, Mono) is a compile/API-compatibility target — its wire codecs, value types, and datagram transports run, but because that BCL has noAesGcm/ECDiffieHellman, the cryptographic handshake throwsPlatformNotSupportedException; a working handshake needs netstandard2.1 (AES-GCM) or net8.0+.
- Usage — getting started: client/server handshakes, options, and the datagram transport API.
- Architecture — the hybrid native/managed design and how the engines and backends fit together.
- Supported protocols — version/platform matrix, cipher suites, credential modes, and interop status.
- Security model — threat model and hardening notes.
- NativeAOT & trimming — AOT/trimming compatibility and guidance.
src/ the Dtls library
tests/ unit, integration, and OpenSSL/Schannel interop tests
samples/ UDP echo client/server
docs/ usage, architecture, security model, supported protocols, AOT
dotnet build
dotnet testThe native backends require their host OS: the Schannel DTLS 1.2 backend and its tests run on Windows; the OpenSSL DTLS 1.2 backend and its tests run on Linux. On a Windows machine, build and test the Linux side with WSL:
# from WSL (the repo is visible at /mnt/<drive>/...)
./eng/wsl-verify.shTests that need a specific OS no-op elsewhere, so the suite is green on every platform.
This is a security-protocol implementation; see docs/security.md for the threat model and hardening notes. DTLS 1.0 is deprecated (RFC 8996) and is off by default.
MIT.