Tern

tls

The tls module encrypts connections with TLS 1.2 and 1.3. Importing it does three things: tls.connect opens verified TLS connections as ordinary net.Conn values, the HTTP clients (http.get, http.fetch) accept https:// URLs, and http.listen_tls (or roost.serve_tls) serves HTTPS. It uses aws-lc (the library under rustls), which tern builds and links statically into programs that import tls, and only those, so the program runs on machines without OpenSSL installed. See Where TLS comes from.

Compiles (not run here)
import tls
import http
import roost

fn main():
    res = http.get("https://example.com/")
    if http.failed(res):
        print("request failed:", res.body)      # e.g. "tls handshake: certificate verify failed: ..."
    else:
        print(res.status, len(res.body))

Without import tls, an https:// URL fails with the message https:// needs \import tls\`, androost.serve_tls` is a runtime error saying the same.

Clients

fn connect(host: str, port: int) net.Conn
fn connect_insecure(host: str, port: int) net.Conn
fn upgrade(c: net.Conn, host: str) bool
fn version(c: net.Conn) str
fn error() str
fn trust(ca_file: str) bool

tls.connect connects, does the TLS handshake, and checks the server's certificate: it must chain to a trusted root and name host (a DNS name or an IP address). Check c.ok(); when it is false, tls.error() says why (a refused connection, a failed name lookup, certificate verify failed: hostname mismatch, ...). The connection is an ordinary net.Conn, so c.read, c.read_line, c.read_exact, c.write and c.close encrypt and decrypt, and like every socket wait, a handshake or a read waits only in its task.

Compiles (not run here)
import net
import tls

fn main():
    c = tls.connect("example.com", 443)
    if not c.ok():
        print("can't connect:", tls.error())
        return
    print(tls.version(c))                          # "TLSv1.3"
    c.write("HEAD / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
    print(c.read_line().trim())                    # "HTTP/1.1 200 OK"
    c.close()

tls.upgrade starts TLS on a connection that is already open, for protocols that begin in plain text and switch (SMTP's STARTTLS, PostgreSQL's SSLRequest). connect_insecure skips the certificate check; use it only for tests, never across a network you don't control.

Trusted roots are the system's CA bundle: /etc/ssl/cert.pem on macOS, and /etc/ssl/certs/ca-certificates.crt (Debian, Ubuntu), /etc/pki/tls/certs/ca-bundle.crt (Fedora, RHEL) and the like on Linux. The environment variables SSL_CERT_FILE and SSL_CERT_DIR override that. tls.trust(ca_file) adds the CA certificates in a PEM file for the rest of the program (a company CA, or a development CA such as mkcert's); it returns false, with tls.error() saying why, if the file can't be read.

Sessions are resumed: after a first full handshake with a server, the next connection to it uses a session ticket and skips the certificate check and the expensive key agreement.

With Result: tls.dial(host, port) Result[net.Conn, str], e.g. c = tls.dial("example.com", 443)?, with errors like "tls: handshake: certificate verify failed: hostname mismatch" (and net.dial for plain TCP).

Servers

fn roost.serve_tls(r: roost.Router, port: int, cert: str, key: str)
fn roost.start_tls(r: roost.Router, host: str, port: int, cert: str, key: str) roost.Server
fn server(cert: str, key: str) Server
fn accept(c: net.Conn, s: Server) bool

cert is a PEM file with the server's certificate followed by any intermediate certificates (Let's Encrypt's fullchain.pem), and key is its private key (privkey.pem). A file that can't be loaded, or a key that doesn't match the certificate, is a runtime error at startup. Each connection's handshake runs in the connection's task.

Compiles (not run here)
import tls
import roost

fn main():
    r = roost.router()
    r.get("/", fn(req) roost.text("hello over https"))
    roost.serve_tls(r, 8443, "fullchain.pem", "privkey.pem")

For a TLS server that isn't HTTP, accept plain connections and call tls.accept in each connection's task:

Compiles (not run here)
import net
import task
import tls

fn serve_one(c: net.Conn, s: tls.Server):
    if not tls.accept(c, s):          # a client that isn't speaking TLS, or gave up
        c.close()
        return
    c.write("hello, " + c.read_line())
    c.close()

fn main():
    s = tls.server("cert.pem", "key.pem")
    l = net.listen(9443)
    while true:
        c = l.accept()
        task.spawn(fn() serve_one(c, s))

For development, mkcert localhost or openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -keyout key.pem -out cert.pem -days 365 -subj /CN=localhost -addext subjectAltName=DNS:localhost makes a certificate; clients then need tls.trust("cert.pem") (or SSL_CERT_FILE).

ALPN: choosing the protocol

fn set_alpn(s: Server, protocols: [str])
fn connect_alpn(host: str, port: int, protocols: [str]) net.Conn
fn alpn(c: net.Conn) str

Application-Layer Protocol Negotiation lets the client and server agree, during the handshake, on what they will speak over the connection: "h2" for HTTP/2 (which gRPC over TLS requires), "http/1.1", or any other registered name. tls.set_alpn gives a server the protocols it speaks, preferred first; a client gets the first of them that it offered. A client that offers only other protocols fails the handshake (the no_application_protocol alert, as RFC 7301 says), and one that offers none gets none: tls.alpn(c) is then "", and the server decides whether to go on. tls.connect_alpn connects like tls.connect, offering protocols, and tls.alpn(c) says which one the server chose ("" if it chose none, or for a plain connection).

Compiles (not run here)
import net
import task
import tls

fn serve_one(c: net.Conn, s: tls.Server):
    if not tls.accept(c, s) or tls.alpn(c) != "h2":   # not TLS, or not HTTP/2: refuse
        c.close()
        return
    # ... speak HTTP/2 on c
    c.close()

fn main():
    s = tls.server("cert.pem", "key.pem")
    tls.set_alpn(s, ["h2"])
    l = net.listen(8443)
    while true:
        c = l.accept()
        task.spawn(fn() serve_one(c, s))

The grpc package serves gRPC over TLS this way (grpc.start_tls). roost.serve_tls sets no ALPN, so clients speak HTTP/1.1, as they do when the server doesn't answer their offer.

A TLS connection may be read by one task and written by another at the same time (a reader task and a writer task, as the grpc package's connections are): the session is taken in turns, never across a wait.

Performance

A one-thread HTTPS server on Linux (Docker, arm64, 4 CPUs), with the same ECDSA P-256 certificate and TLS 1.3 with the hybrid post-quantum X25519MLKEM768 key exchange, against Go (net/http) and Rust (axum + rustls on aws-lc-rs). Method and machine load are in bench/std/results.md:

server, 1 threadTern (aws-lc)Tern (TERN_TLS=system, OpenSSL 3.0)Rust (rustls)Go
keep-alive requests/s272,576243,566239,753158,784
CPU per keep-alive request3.2 us3.7 us3.7 us5.8 us
full handshakes/s8,1156,7737,2325,968
CPU per full handshake80 us146 us89 us165 us
p99 at 100,000 keep-alive requests/s3.3 ms6.1 ms5.7 ms21.0 ms
p99 at 4,000 handshakes/s3.9 ms18.7 ms4.9 ms13.1 ms

The client, on macOS with one thread (Tern with OpenSSL 3.6, before aws-lc was bundled):

client, 1 threadTernGoRust
new connection per request2,585 req/s1,570 req/s2,574 req/s
keep-alive, sequential40,376 req/s29,818 req/s22,192 req/s
50 concurrent keep-alive clients120,391 req/s81,740 req/s77,998 req/s

Tern reads each socket once per request, whatever has arrived, and knows when the socket is drained, so a keep-alive request costs one read(2) and one write(2). Tern and rustls resume sessions on new client connections; Go's client doesn't by default.

Where TLS comes from

The first build that imports tls for a target downloads aws-lc and compiles it, once, into the build cache (~/.cache/tern/aws-lc-<version>/<target>/); later builds reuse it. With git installed, the download is a shallow sparse clone of the pinned release tag that fetches only the files the build needs (about 8 MB, 41 MB on disk) and is checked against the tag's pinned commit; without git, tern downloads the release tarball (about 130 MB) with curl and checks its pinned SHA-256. Either way tern prints a line when it starts:

tern: downloading aws-lc 1.61.4 (git, about 8 MB; once, for `import tls`)...
tern: building aws-lc 1.61.4 for native (once, for `import tls`; about a minute)...

Compiling takes 20 to 60 seconds per target, with the same C compiler tern uses for the target: Xcode on macOS and iOS, the NDK for Android, and Docker for the Linux targets (linux, linux-x86_64, linux-static). The version, commit, checksum and the list of files and flags per target are in compiler/targets/awslc.txt; no cmake, Go or Perl is needed, since the assembly comes pregenerated in aws-lc's tree.

Why aws-lc rather than the system's OpenSSL: its X25519, ML-KEM and P-256 are hand-written assembly, so full handshakes cost about half the CPU of OpenSSL 3's (see Performance); the binary carries its TLS library, so the same executable runs on any Linux distribution, and on iOS and Android, which have no OpenSSL; and it's the same crypto that rustls uses.

Other choices, set when building:

settingTLS library
(default)aws-lc, built and cached by tern
TERN_TLS=systemthe system's OpenSSL 3: Homebrew's, linked statically, on macOS; -lssl -lcrypto elsewhere
TERN_OPENSSL=/path/to/prefixany OpenSSL-compatible install with include/ and lib/
TERN_OPENSSL_DYNAMIC=1with one of the two above, links it dynamically

Licenses

A program that imports tls links aws-lc statically; programs that don't contain none of it. aws-lc is available under the Apache License 2.0 or the ISC license, with code inherited from BoringSSL and OpenSSL under the ISC, OpenSSL and SSLeay licenses, and small parts under MIT, BSD-3-Clause and MIT-0. The full texts are in aws-lc's LICENSE and NOTICE files, in the source tree tern unpacks under ~/.cache/tern/aws-lc-<version>/.

When you distribute such a binary, include those license texts with it (in its documentation or an "open source licenses" screen, for example). The OpenSSL and SSLeay licenses also ask for these acknowledgments:

  • This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
  • This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).

With TERN_TLS=system, the program uses the system's OpenSSL 3 instead (Apache-2.0).

Binary size

aws-lc adds about 2 MB to a program that imports tls: a minimal HTTPS GET is 2.3 MB on macOS (2.1 MB stripped) and 2.5 MB on Linux arm64, with no dependency beyond libc. tern compiles aws-lc with each function in its own section and links with dead-code removal, so only the parts the program uses stay in.

Source: docs/std/tls.md. Every example on this page is compiled and run by tern x test docs.