Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-tls

Native Luce Base TLS 1.3 client: tls_stream.Stream (io.Reader/io.Writer) with deadlines and STARTTLS, certificate validation, and a small private-endpoint server. Experimental. MIT OR Apache-2.0.

A library written in luce-base. Latest release 0.7.1.

Install#

luc add dymokomi/luce-tls

Documentation#

luce-tls

Native Luce Base TLS 1.3 client (and a small private-endpoint server). MIT OR Apache-2.0.

Experimental, not security-reviewed. Do not rely on it where a reviewed TLS stack is required.

Using it

tls_stream.Stream owns one TCP connection that is either plain or TLS and implements io.Reader and io.Writer, so IMAP or SMTP code needs no transport glue. It upgrades in place for STARTTLS.

import io
from luce_std import net
from luce_tls import stream as tls_stream

# Implicit TLS (IMAPS 993, SMTPS 465), validated against the public roots.
var stream = try tls_stream.Stream.connect("imap.example.com", 993, true)
try io.write_all(&stream, b"a1 CAPABILITY\r\n")
var buffer: u8[4096]
let count = try stream.read(buffer)     # zero: end of stream (close_notify)
try stream.close()                      # close_notify, then close the socket

# STARTTLS (IMAP 143, SMTP submission 587).
var mail = try tls_stream.Stream.connect("smtp.example.com", 587, false)
# ... greeting, EHLO, STARTTLS and its 220 reply, all through `mail` ...
try mail.start_tls("smtp.example.com")
CallMeaning
Stream.connect(host, port, tls, deadline = net.Deadline(), cancellation = none, policy = Trust(), alpn = "") -> Stream!resolve with net.resolve_all, try each address in order, handshake when tls
Stream.plain(connection) -> Streamadopt a connected socket as a plain stream
stream.start_tls(host, policy = Trust(), alpn = "") -> !STARTTLS on the same socket; discard plaintext buffered after the server's reply first
stream.is_secure() -> boolwhether TLS protects the stream
stream.set_deadline(deadline, cancellation = none)absolute deadline and cancellation for the following reads, writes and close
stream.read(buffer) -> usize!, stream.write(data) -> usize!Reader/Writer under the stream's deadline; write sends everything
stream.read_within(buffer, deadline, cancellation = none) -> usize!one read with its own deadline and cancellation
stream.write_within(data, deadline, cancellation = none) -> !send everything with its own deadline and cancellation
stream.pending() -> usizedecrypted bytes read returns without touching the socket
stream.wait(interest = read, deadline, cancellation) -> net.Readiness!readable at once when bytes are pending, otherwise a socket wait
stream.descriptor(), stream.peer_address()for a net.Poller; check pending() first, never read the descriptor
stream.closed_by_peer() -> boolthe server sent close_notify
stream.close() -> !, stream.destroy()close (closenotify when secure); destroy skips closenotify
stream.set_nonblocking(enabled) -> !, stream.is_nonblocking()nonblocking mode, for an event loop: no transfer waits
stream.begin_tls(host, policy = Trust(), alpn = "") -> !start the handshake without waiting (nonblocking mode); the ClientHello is queued
stream.continue_tls() -> bool!advance the handshake with what arrived; true once secure
stream.queued() -> usize, stream.flush() -> bool!records waiting for the socket; send them, true when none is left
stream.accept_tls(der, d) -> !answer a TLS client on a plain stream as the small private-endpoint server

Trust policies: Trust.public_roots() (the default Trust(): the bundled Mozilla roots), Trust.pinned_issuer(x, y) for a private or test server whose P-256 leaf is signed by (or self-signed with) that key, and Trust.p384_root(x, y) for a strict chain under an explicit P-384 root.

The socket is kept nonblocking and every transfer waits through readiness like net.DeadlineStream. A read that times out (net.timed_out) or is cancelled (net.cancelled, e.g. by another thread ending an IMAP IDLE) leaves the stream usable: a partial TLS record is kept and the next read continues it.

In nonblocking mode (set_nonblocking(true), typically on a connection begun with net.Connection.start_connect) an event loop watches descriptor(): for write readiness while queued() is not zero, otherwise for read readiness. read and write fail with io.would_block instead of waiting (write accepts up to one record, which waits in the stream's outgoing queue if the socket cannot take it all, and accepts nothing while records are queued), and the handshake advances step by step: begin_tls, then continue_tls on each readiness until it answers true. The client handshake is one resumable state machine (client.Handshake: start, step); the blocking connect and start_tls run it to its end.

The older session API (connect, connect_public, connect_p384_chain, connect_trusted, upgrade_client, accept, send, receive, pending with a caller-owned net.Connection and Secrets) remains for blocking use.

Protocol coverage

  • TLS 1.3 only (RFC 8446). SNI is sent for DNS names. HelloRetryRequest (cookie and group change) is handled. Post-handshake NewSessionTicket is ignored and KeyUpdate is honoured (and answered on the next write). Records are fragmented at 2^14 bytes. A CertificateRequest is answered with an empty Certificate.
  • Cipher suites: TLSAES128GCMSHA256, TLSAES256GCMSHA384 and TLSCHACHA20POLY1305_SHA256. Key exchange: X25519, and secp256r1 after a HelloRetryRequest.
  • CertificateVerify: ecdsasecp256r1sha256, ecdsasecp384r1sha384 and rsapssrsae_sha256/384/512. Certificate signatures: ECDSA P-256/P-384 with SHA-224/256/384/512, RSA PKCS#1 v1.5 with SHA-224/256/384/512 and RSA-PSS with SHA-256/384/512 (RSA keys 2048–8192 bits). SHA-1 and MD5 are refused.
  • Certificate validation (chain): the leaf must match the host by a subjectAltName dNSName (single leftmost wildcard label; no common-name fallback), be within its validity period, not be a CA, and allow digitalSignature and TLS server authentication when it states usages. A path is built from the leaf to a trust anchor through the presented certificates in any order (extra, duplicate or unparsable ones are ignored); each issuer must be a CA within its validity, allow keyCertSign and server authentication when stated, and respect pathLenConstraint. Unknown critical extensions and name constraints are rejected. Certificate policies are not processed: a critical certificatePolicies extension is accepted only when its qualifiers are CPS pointers (as BearSSL does), and other critical policy extensions are refused.
  • Trust anchors: roots.lucb, generated by tools/mozilla_roots.py from Mozilla NSS certdata.txt: 119 roots trusted for TLS server authentication with RSA, P-256 or P-384 keys (roots with a server distrust-after date are left out). Regenerate it to update the set. Anchors.single trusts one key; Anchors.named_list holds up to eight Name-and-key anchors (RFC 5280 §6.1.1). An anchor is only a Name and key: its certificate's own CA flag, validity and EKU are not checked, and a leaf cannot be its own anchor.

Verified live with tools/live_smoke.py on 2026-10-02: IMAPS, SMTPS and SMTP/IMAP STARTTLS against imap.gmail.com, smtp.gmail.com (465 and 587), imap.mail.me.com, smtp.mail.me.com, outlook.office365.com (993 and 143), smtp.office365.com, imap.fastmail.com and smtp.fastmail.com.

Not supported: TLS 1.2 (the next step: some older mail hosts only speak it), resumption, 0-RTT, client certificates, OCSP/CRL revocation, fetching missing intermediates (AIA), name constraints, IP-address SANs and the system trust store.

Tests

luc test

Every check is a test program, tests/<name>/main.lucb (tests/handshake, tests/stream, tests/x509_suite, ...), built and run by luc test. They cover loopback client/server handshakes, Stream reads and writes across records, pending plaintext, deadline timeouts that resume, cancellation from another thread, a plain exchange then an in-place STARTTLS upgrade that answers a CertificateRequest, close_notify, a wrong pin, the captured Lucia OS Caddy/Let's Encrypt chain, and negative chain, trust, hostname, time, extension, ordering and tamper cases. tests/chains/ holds chains captured from Gmail, iCloud, Outlook and Fastmail mail servers (tools/capture_chains.py), validated against the bundled roots at their capture time, with wrong-host, expired, not-yet- valid, untrusted-root, broken-signature, missing-intermediate and reordered variants. Sanitizer checks cover generated C and the runtime. CI is deterministic and uses no network. python3 tools/live_smoke.py (not in CI) handshakes with real mail servers and runs IMAP CAPABILITY/LOGOUT or SMTP EHLO/QUIT over implicit TLS and STARTTLS. These checks do not establish complete RFC 5280 policy processing, revocation coverage, leak freedom or side-channel safety.

Reference suites

Converted reference tests run in every mode (MIT or Apache-2.0 sources; data only, see NOTICE.md; converters in tools/ regenerate everything):

SuiteSourceResult
RFC 8448 §3 1-RTT tracetools/rfc8448_vectors.py23 HKDF steps, 48 items and all 9 records byte for byte (both directions decrypt)
OpenSSL TLS13-KDFevpkdf_tls13_kdf.txt, tools/openssl_tls13_kdf.py154 extract + 408 expand pass
BearSSL X.509test/x509/alltests.txt, tools/bearssl_x509.py26 accepted, 21 rejected, all as expected
OpenSSL verifytest/recipes/25-test_verify.t, tools/openssl_verify.py21 accepted, 76 rejected, all as expected

Every case is either run, given this client's own verdict with a reason, or listed as out of scope:

  • RFC 8448: the client writes legacyrecordversion 0x0303 on every record; the trace's initial ClientHello uses 0x0301, which RFC 8446 §5.1 also allows, so that byte is the one difference compared. The trace's server certificate has a 1024-bit RSA key, which is refused (checked); its CertificateVerify signature is therefore not verified here.
  • TLS13-KDF out of scope (9): mode EXTRACTANDEXPAND (OpenSSL itself refuses it) and 8 FIPS-provider-only checks (SHAKE-256/SHA-512/256 digests, short keys, approval indicators).
  • BearSSL, different verdict (tests/x509/bearssl/POLICY.txt): goodName3 (no common-name fallback), hashSHA1 and secp256r1-sha1 (SHA-1 refused), rsa1017 (RSA below 2048 bits). Not expressible (5): directTrust, ignoredSignature1/2 (end-entity anchors), hashSHA256Unsupported (configurable hash set), secp521r1 (P-521).
  • OpenSSL verify, different verdict (tests/x509/openssl/POLICY.txt, 37): anchors are Name and key, so a trusted certificate's CA flag and EKU are not checked (5 accept); a leaf cannot be its own anchor (2 reject); RSA below 2048 bits, MD5, SHA-1 and SHA-3 signatures, Ed25519, RSASSA-PSS-only keys, name constraints, a critical OCSP no-check extension and pathLen without cA are refused; the 2048-bit floor applies at every OpenSSL auth level (1 accept). Out of scope (93, SKIPPED.txt): OpenSSL auxiliary trust settings on certificates (53), client, code-signing and timestamp purposes (31), and the -checksssig, -policycheck, -verifydepth and -x509_strict options (9).

Dependencies#

PackageVersion
dymokomi/luce-cryptonewest
dymokomi/luce-stdnewest

Versions#

0.7.1

Browse source · pack · commit 5422c3186960

SHA-256 8b25ac5888ce187e8d95849d1801de9a544047b2dd02aa758a30ebd7b928ee29

luce-tls 0.7.1: batch release

0.7.0

Browse source · pack · commit 0815dcaedf1f

SHA-256 cb5fd9d0e5afdce42b5d0b7631cd77c3a462ce1d4540c940ee861959c1c8a24d

byte spans compare with ==; dependencies name no version