TLS 1.3 (RFC 8446) written in Oberon, for the voc compiler and for polpo, which uses the same files with adapted platform imports. It uses only 32 bit integers, so it runs wherever these compilers do, and the cryptography is its own: no OpenSSL.
-
The client: X25519, or P-256 when the server asks for it with a HelloRetryRequest; TLS_AES_128_GCM_SHA256; randomness from
/dev/urandom. -
Checking the server:
- its certificate chain must lead to a root of
$SSL_CERT_FILEor/etc/ssl/certs/ca-certificates.crt. RSA PKCS#1 and RSASSA-PSS, and ECDSA P-256, P-384 and P-521 signatures are understood; - validity, CA, key usage and name constraints are checked;
- the certificate must be for the host name or IP address;
- CertificateVerify and Finished must be right.
Otherwise the connection is refused with the alert that says why.
ConnectPinnedaccepts a server by the hash of its key instead, for protocols that trust on first use (Gemini). - its certificate chain must lead to a root of
-
Client certificates: when a server asks for one, the client presents an identity (
TLS13Live.SetIdentity) and signs its CertificateVerify, or sends an empty Certificate. -
After the handshake: KeyUpdate is followed both ways, and a connection that ends without close_notify is reported.
-
The server side (
TLS13Server): the same suite and groups, with a HelloRetryRequest when a client offers neither key share. The certificate is chosen by the host name the client asks for (SNI,AcceptBy), so one port can serve several hosts. There are no session tickets. -
Identities (
TLSIdentity): a certificate chain and its key, ECDSA P-256 or RSA (2048 bits or more). They're read from PEM (CERTIFICATE;EC PRIVATE KEY,RSA PRIVATE KEYorPRIVATE KEY) and checked to belong together. They sign with ecdsa_secp256r1_sha256 (RFC 6979 nonces) or rsa_pss_rsae_sha256 (CRT, each signature checked before it is sent). Servers and clients use them alike. -
New certificates (
TLSCertGen): self-signed X.509 v3 with a new P-256 key, for an identity (name and mail) or a server (with its host name), written as PEM, with the key as PKCS #8. So openssl is not needed to make them.
The arithmetic is not constant time: the code suits experimental servers and clients rather than places where an attacker can measure many handshakes.
A client:
IF TLS13Live.Connect("example.org", "443", s) THEN
ok := TLS13Live.WriteAppString(s, request);
WHILE TLS13Live.ReadAppMax(s, buf, LEN(buf) - 1, n) DO ... END;
TLS13Live.Disconnect(s)
ELSE Out.String(TLS13Live.lastError)
ENDWith a client certificate: TLSIdentity.Load(cert, key, id), then TLS13Live.SetIdentity(id)
before connecting. After a connection, TLS13Live.certPin is the SHA-256 of the server's
certificate and TLS13Live.keyPin that of its key.
On VOC's Linux model-2 profile, Begin(host, fd, state) takes ownership of an
already connected descriptor and makes it nonblocking. Repeated
PollHandshake(state) calls return 0 while pending, 1 after verification
and Finished, or -1 on failure. The caller supplies the overall deadline
and calls CloseNow on cancellation. The asynchronous path uses the same
chain, hostname, CertificateVerify and Finished checks as the blocking path.
After verification, ReadSome(state, bytes, offset, count) and WriteSome
return a positive byte count, -2 when pending, or -1 on failure.
ReadSome returns zero for close_notify. Retain the same unacknowledged
write span when retrying after -2; a positive result acknowledges plaintext
only after its complete encrypted record has been flushed. Writes accept
at most 16384 plaintext bytes at a time. Partial record headers, bodies and
writes are retained across calls. Post-handshake KeyUpdate responses are
queued in order with application records. FlushOutput advances pending
output and returns 0, 1 or -1 using the handshake status convention.
UseNonblocking switches an established blocking client or server session
to the resumable record API. Use ReadSome/WriteSome thereafter; the
blocking record entry points reject nonblocking states. CloseNow closes
immediately and clears keys, including a pending handshake. It aborts rather
than waiting to send close_notify; Disconnect has the same prompt behavior
for nonblocking states. Rebuild modules embedding TLS13Live.State when
updating this interface.
The API is single-threaded. The current certificate-handshake parser has
shared state, so resumable handshakes are serialized; established sessions
can progress independently. Do not change identity/pinning settings during
an active handshake. Blocking client handshakes are refused while a
resumable handshake owns that parser. Certificate verification and CA-file
loading remain synchronous computation and file I/O. These entry points
require VOC's Sockets descriptor APIs; this profile has been tested on
Linux, with other platform bindings requiring separate validation.
A server, on a connection the caller accepted (with a timeout set on it):
IF TLS13Server.Load("cert.pem", "key.pem", id) THEN
...
IF TLS13Server.Accept(fd, id, s) THEN (* s is then a TLS13Live.State, read and written as above *)
...
TLS13Live.Disconnect(s)
ELSE Out.String(TLS13Server.lastError)
END
ENDTLS13Server.AcceptBy(fd, choose, s) takes a procedure that gives the certificate for the host
name of the client (TLS13Server.serverName), or NIL to refuse it with unrecognized_name.
A new self-signed certificate: TLSCertGen.SelfSigned(name, mail, dnsName, years, certPEM, keyPEM); pass "" for the mail or the host name you don't want.
| modules | |
|---|---|
TLSBytes, BIT, TLSNum |
byte buffers, 32 bit words, big numbers (Montgomery) |
TLSSHA256, TLSSHA512, TLSHKDF |
hashes, HMAC, HKDF |
TLSAESGCM, TLSX25519, TLSECDSA, TLSRSA |
AES-128-GCM, X25519, ECDSA and ECDH (P-256/384/521), RSA |
TLSASN1, TLSBase64, TLSPEM |
DER, Base64, PEM (read and write) |
TLSX509, TLSX509Ext, TLSX509Names, TLSX509Validity, TLSNameConstraints, TLSX509Chain, TLSSig, TLSCABundle, TLSNow |
certificates and their chains |
TLS13Handshake, TLS13Keys, TLS13Records, TLS13EncHandshake, TLS13Certs, TLS13Finished, TLS13ClientFinished, TLS13Application, TLS13Random |
the protocol |
TLS13Live |
client connections |
TLSIdentity, TLSCertGen, TLS13Server |
identities, new certificates, the server side |
httpsPure |
HTTPS for the http module |
Programs: tlsConnect host port (connect and report), httpsGet host port path [file],
tlsServe cert key port [n] (a test server), tlsIdent host port path [cert key] (a connection
with a client certificate), and certGen name [mail] [dns] (print a new certificate and key).
make # the dependencies (strutils, base64, Internet, http) are fetched into deps/
make tests # the unit tests, against the files in test/certs
make async-tests # fragmented live TLS, resumable records and the blocking APIasync-tests uses the installed VOC dependencies, Python 3 and OpenSSL's
command-line tool for temporary test certificates. It exercises split TLS
headers and bodies, KeyUpdate/new keys, close_notify, HelloRetryRequest,
verified connections and hostname/CA rejection. It compiles the current
TLS13Live source into an isolated temporary build.
The hexadecimal test dumps use Out.HexDigits(value, width). Use a VOC
installation providing that procedure; Out.Hex has ETH Oberon's one-argument
interface. The five hexadecimal-dump tests match Polpo's versions at
c9795fc1, printing two uppercase digits per byte.
After the import of a module changes, run make clean first: voc keeps the import list of an old
symbol file when the interface stays the same, and the link then misses the new module.
The tests in tools/ start real servers to test against (testservers.py, keyupdate.sh,
hrrserver.sh). For client certificates, openssl s_server -verify 1 -www shows what it got.
polpo keeps a copy in src/lib/tls, copied with loksh vocsync.From tls/src/X.Mod ... src/lib/tls,
which adapts platform imports (Linux0 for Linux0 := unixNet). Both systems import Out
directly. Its tests are in
src/lib/tls/test (TLS_TEST_CERTS=src/lib/tls/test/certs loksh TLSTestChain.Run and so on). The
Gemini clients (dcs, DCS, Pishmish) and servers (agena, cobweb) of polpo are built on it.