SharpDTLS 0.0.1

SharpDTLS

DTLS 1.0/1.2/1.3 and TLS 1.0/1.1/1.2/1.3 client and server written in C#. The cryptography comes from BouncyCastle; the protocols are implemented here. Targets netstandard2.0, net472, net8.0 and net10.0.

A client offers every enabled version in one ClientHello and a server answers with the highest one both sides support. DTLS 1.2 and DTLS 1.3 are on by default, and so are TLS 1.2 and TLS 1.3. To enable the older versions, set MinimumVersion.

Implements the following RFCs:

1. The Transport Layer Security (TLS) Protocol Version 1.3 RFC9846 (obsoletes RFC8446)
2. The Datagram Transport Layer Security (DTLS) Protocol Version 1.3 RFC9147
3. The Transport Layer Security (TLS) Protocol Version 1.2 RFC5246
4. Datagram Transport Layer Security Version 1.2 RFC6347
5. Connection Identifier for DTLS 1.2 RFC9146
6. DTLS Extension to Establish Keys for the Secure Real-time Transport Protocol (SRTP) RFC5764
7. TLS Extensions: server name, OCSP stapling and more RFC6066
8. Application-Layer Protocol Negotiation RFC7301
9. Raw Public Keys in TLS and DTLS RFC7250
10. TLS Certificate Compression RFC8879
11. Record Size Limit Extension for TLS RFC8449
12. Keying Material Exporters for TLS RFC5705
13. Session resumption with session tickets RFC5077, extended master secret RFC7627
14. Pre-shared keys RFC4279, SRP RFC5054 and TLS-PWD RFC8492

DTLS

The DTLS server and client send and receive datagrams through a transport: ServerTransport and ClientTransport in SharpDTLS.UDP use a UDP socket. To run DTLS over something else, such as an ICE connection, implement IServerTransport or IClientTransport.

Create the server. Without a key pair and a certificate it generates a self-signed certificate:

var serverTransport = new ServerTransport(new IPEndPoint(IPAddress.Any, 8888));
var server = new DtlsServer(serverTransport);
server.ApplicationDataReceived += (sender, e) =>
{
    Console.WriteLine($"Server received: {Encoding.UTF8.GetString(e.Data)}");
    e.Connection.SendApplicationData(Encoding.UTF8.GetBytes("Hello from server!"));
};

To use your own certificate, pass it with its key pair: new DtlsServer(serverTransport, keyPair, certificate).

Create the client and start the handshake. The handshake runs in the background and HandshakeFinished is raised when it completes, or Failed when it does not:

var clientTransport = new ClientTransport(new IPEndPoint(IPAddress.Loopback, 8888));
var client = new DtlsClient(clientTransport);
client.HandshakeFinished += (sender, e) =>
{
    Console.WriteLine($"Handshake finished: version 0x{client.NegotiatedVersion:X4}");
    client.SendApplicationData(Encoding.UTF8.GetBytes("Hello from client!"));
};
client.ApplicationDataReceived += (sender, data) => Console.WriteLine($"Client received: {Encoding.UTF8.GetString(data)}");
client.Failed += (sender, ex) => Console.WriteLine($"Handshake failed: {ex.Message}");
client.BeginHandshake();

When done, call client.Close() and dispose of the transports.

TLS

TlsStream runs TLS over any Stream, such as a NetworkStream, and is a Stream itself:

using var tcp = new TcpClient();
await tcp.ConnectAsync("example.com", 443);
using var tls = await TlsStream.ConnectAsync(tcp.GetStream(), client =>
{
    client.ServerName = "example.com";
    client.ServerCertificateValidator = new CertificateValidator().ForServer("example.com");
});
await tls.WriteAsync(request, 0, request.Length);
int read = await tls.ReadAsync(buffer, 0, buffer.Length);

On the server side, TlsStream.AcceptAsync(new TlsServer(), stream) serves a client connected on the stream.

Certificate validation

By default, a client accepts any certificate from the server and only checks that the server holds its private key. To validate the chain against the operating system's trust store and check the host name, set ServerCertificateValidator:

client.ServerCertificateValidator = new CertificateValidator().ForServer("example.com");

To trust only your own CA, pass its certificate: new CertificateValidator(new[] { caCertificate }). A server checks client certificates the same way with ForClient().

CertificateValidator is the default implementation of ICertificateValidator. To validate some other way, implement Validate, which throws a DtlsException with the alert to send when the chain is not acceptable, and plug it in the same way:

client.ServerCertificateValidator = new MyCertificateValidator().ForServer("example.com");