ianic / tls.zig

tls.zig Zig TLS library, characteristics: • TLS 1.2 and TLS 1.3 client • TLS 1.3 server • handles client authentication • tested with many domains, handles badssl URL's • options to select client cipher suites to use, named groups, ... • can configure Wireshark to show decrypted traffic • better performance, more modular, more testable, connect to more real world sites than standard library implementation Client Here is simple example of how to use library. To upgrade existing tcp connection to the tls connection call : After that you can use read/write methods as on plain tcp connection. Options Second parameter in calling are tls.config.Client they can be used to force subset of implemented ciphers, set client authentication parameters, allow self insecure signed certificates, collect handshake diagnostics, exchange session keys with Wireshark to view decrypted traffic. Select cipher suite To use just ciphers which are graded secure or recommended on https://ciphersuite.info: can be used to force tls 1.3 only or tls 1.2 only ciphers. Or to reorder cipher preferences. Client authentication If server requires client authentication set attribute in options. You need to prepare certificate key pair with client certificate(s) and client private key. When client receives certificate request from server during handshake it will respond with client certificates message build from provided certificate bundle and client certificate verify message where verify data is signed with client private key. If authentication is not provided client will respond with empty certificate message when server requests authentication (as specified in RFC). Logging tls session keys Session keys can be written to file so that external programs can decrypt TLS connections. Wireshark can use these log files to decrypt packets. You can tell Wireshark where to find the key file via Edit→Preferences→Protocols→SSL→(Pre)-Master-Secret log filename. Key logging is enabled by setting the environment variable SSLKEYLOGFILE to point to a file. And enabling key log callback in client options: Server Library also has minimal, TLS 1.3 only server implementation. To upgrade tcp to tls connection: Examples Top sites Starting from Cloudflare list of 10000 top domains, filtering those which can't be resolved got list of ~6k domains which are used to test establishing tls connection. If the connection fails test runs curl on the same domain, if curl can't connect it is count as error, if curl connect counts as fail. For each domain test reports tls handshake parameters (tls version, cipher suite used, named group and signature scheme). Zig's std library tls implementation on the same domains list: When I found domain which fails I use http_get example to test whether it is transient error or point to something interesting. Now only transient errors are left in that domains group. http get This example will connect to the domain, show response and tls statistic. You can change tls options to force tls version or specific cipher. badssl Uses urls from badssl.com to test client implementation. All ciphers Tries all supported ciphers on some domain. Using cloudflare.com as example because it supports all implemented ciphers. Server and client example Create local development certificates and keys: This uses minica tool. Go compiler and go install dir in the path are required. Start server and connect to with client to the server. Client authentication After we have certificates created in previous example, here we will start Go tls server which requires client authentication and connect to that server with various different rsa and ec certificates using both tls 1.2 and 1.3. Equivalent is: Credits • Michael Driscoll for creating The Illustrated TLS 1.2 Connection and The Illustrated TLS 1.3 Connection. Those are really useful for understanding what each byte means. • @jedisct1 for zig-cbc library. Copied to src/cbc with padding changed from pkcs to tls. • @clickingbuttons for rsa package. Copied to src/rsa from branch of this PR