dymokomi/luce-tls
Source of release 0.7.1
0.7.1 / README.md
# 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.
```luce
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")
```
| Call | Meaning |
| --- | --- |
| `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) -> Stream` | adopt 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() -> bool` | whether 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() -> usize` | decrypted 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() -> bool` | the server sent close_notify |
| `stream.close() -> !`, `stream.destroy()` | close (close_notify when secure); destroy skips close_notify |
| `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: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384 and
TLS_CHACHA20_POLY1305_SHA256. Key exchange: X25519, and secp256r1 after a
HelloRetryRequest.
- CertificateVerify: ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384 and
rsa_pss_rsae_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
```sh
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):
| Suite | Source | Result |
|---|---|---|
| RFC 8448 §3 1-RTT trace | `tools/rfc8448_vectors.py` | 23 HKDF steps, 48 items and all 9 records byte for byte (both directions decrypt) |
| OpenSSL TLS13-KDF | `evpkdf_tls13_kdf.txt`, `tools/openssl_tls13_kdf.py` | 154 extract + 408 expand pass |
| BearSSL X.509 | `test/x509/alltests.txt`, `tools/bearssl_x509.py` | 26 accepted, 21 rejected, all as expected |
| OpenSSL verify | `test/recipes/25-test_verify.t`, `tools/openssl_verify.py` | 21 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 legacy_record_version 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 EXTRACT_AND_EXPAND (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 -check_ss_sig, -policy_check, -verify_depth and -x509_strict options (9).