The same kind of handler as any plain-HTTP example, served over TLS 1.3. TLS
lives in the server's epoll worker: it runs the handshake, encrypts and
decrypts records, and hands record crypto to the kernel (kTLS) when the host
can. The handler never sees any of it, so turning a plain server into an HTTPS
one is a single ServerConfig field, tls_config.
TLS is opt-in at build time: it needs Mbed TLS 4 and the -d vanilla_tls
flag. Linux only: new_server refuses tls_config on any backend but epoll.
v -d vanilla_tls run examples/https/srcIt listens on :8443 (main.v), IPv4. On the first run it
issues a self-signed certificate for localhost, 127.0.0.1 and ::1 and
writes it to certs/ in the working directory (cert.pem, and key.pem with
mode 0600). Later runs load that identity again, so a client that trusts
certs/cert.pem keeps working across restarts:
curl -i --cacert certs/cert.pem https://localhost:8443/HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 13
Connection: keep-alive
Hello, HTTPS!
curl -I gets the same headers and no body. Any other method on / gets a
405 with Allow: GET, HEAD, and any other path a 404:
curl -i --cacert certs/cert.pem -X POST https://localhost:8443/HTTP/1.1 405 Method Not Allowed
Allow: GET, HEAD
Content-Length: 0
Connection: keep-alive
Without --cacert, curl refuses the certificate (self-signed certificate,
exit 60): the identity is real, just not signed by a CA it knows. A plaintext
request to the port gets no HTTP answer: the server reads it as a broken
ClientHello and closes the connection (curl http://localhost:8443/ reports a
reset).
Built without -d vanilla_tls, the program stops at startup:
https: vtls: built without TLS support — rebuild with `-d vanilla_tls` (and install Mbed TLS 4)
Set HTTPS_CERT and HTTPS_KEY to PEM files (a certificate chain and its
key, for example from Let's Encrypt) and load_tls loads them with
tls.new_from_pem instead of issuing one:
HTTPS_CERT=/etc/letsencrypt/live/example.com/fullchain.pem \
HTTPS_KEY=/etc/letsencrypt/live/example.com/privkey.pem \
v -d vanilla_tls -prod run examples/https/srcSetting only one of them is an error, not a fallback to a self-signed
certificate. For a self-signed certificate valid for a real host, pass its
names to tls.new_self_signed(sans: ['DNS:example.com', 'IP:203.0.113.5'])
in load_tls, and delete certs/ first: while its files exist they are
loaded, and sans is ignored.
- The handler is plain HTTP.
routereads the method and path from the request line (http1_1/router) and appends aconstresponse withcore.append_str: no allocation per request (BEST_PRACTICES §3a). It is called with decrypted bytes and its output is encrypted after it returns, so the same function would serve plain HTTP unchanged. - One field makes it HTTPS.
tls_config: cfginServerConfig, wherecfgcomes fromtls.new_self_signedortls.new_from_pem. Leaveio_multiplexingunset: the Linux default, epoll, is the backend that serves TLS. HTTPS connections run on the same worker as plain ones, so everything else a handler can do works here too:.suspendon a database or an upstream, WebSocket takeover, server push,on_worker_start, file bodies handed off withcore.queue_file. - The handshake has a deadline. A connection's first read deadline starts
at accept, so
read_timeout_msalso bounds the handshake: a client that connects and never finishes it is closed silently after 10 s. Without a read timeout the idle timeout does the same. Set one of them on any public HTTPS server (server/README.md). - kTLS when the host has it. After the handshake the server moves record
encryption into the kernel if the
tlsmodule is loaded (modprobe tls), and thensendfile(2)can stream file bodies without a userspace copy (seestatic_assets). Otherwise records stay in Mbed TLS, and the server logs the fallback once. - Parallel crypto needs the right Mbed TLS build. Without
MBEDTLS_THREADING_C(the upstream default, and distro packages such as Arch's) the workers take turns in the crypto library, and the server says so at startup. server/README.md shows how to build it with threading.
v test examples/https/src
v -d vanilla_tls test examples/https/srcmain_test.v calls route directly and runs in any build:
the exact bytes of the 200, HEAD and 404 answers, the 405's status line and
Allow, appending after an earlier response, no allocation over 20k
requests, and load_tls refusing a certificate without its key.
https_e2e_test.v needs -d vanilla_tls on Linux and
serves the example over TLS to a client that verifies the certificate
against cert.pem, as curl --cacert does. It covers localhost and
127.0.0.1, keep-alive, a restart that keeps the identity, the
HTTPS_CERT/HTTPS_KEY path, and a plaintext request that is closed at once
with no HTTP answer.
- server/README.md — TLS: TLS on the epoll worker, kTLS and the threading build
- examples/https_upstream: the client side, calling an HTTPS API from a handler