Skip to content
norayrPublic

About

tls library written in oberon

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

47 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

tls

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.

What it does

  • 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_FILE or /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. ConnectPinned accepts a server by the hash of its key instead, for protocols that trust on first use (Gemini).

  • 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 KEY or PRIVATE 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.

Using it

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)
END

With 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.

Resumable client I/O

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
END

TLS13Server.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.

The modules

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).

Building and testing

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 API

async-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.

In polpo

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.

About

tls library written in oberon

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages