moontls
moontls — the TLS 1.3 protocol state machine for MoonBit (RFC 8446) and DTLS 1.3 over datagrams (RFC 9147): record layers, handshake, key schedule and DTLS-SRTP keying, bytes in and events out. No sockets, no cryptography of its own.
tls
tls13
dtls
rfc8446
rfc9147
moonbit
Author
Version
0.9.1
License
Apache-2.0
Repository
Last updated
9 hours ago
Downloads
386
#moontls
TLS 1.3 for MoonBit (RFC 8446), client and server, and DTLS 1.3 (RFC 9147) for when it runs over datagrams — ciphertext in, ciphertext and plaintext out. No sockets, and not one line of cryptography of its own: the algorithms are mooncrypt's and certificate validation is mooncred's.
// A client: put what the socket gives into `receive`, send what `take` gives.
let config = @tls.Client::new(@roots.mozilla(), alpn=["h2", "http/1.1"])
let conn = @tls.Conn::client(config, "example.com", rand~, now~)
socket.write(conn.take()) // the ClientHello
while !conn.is_connected() {
conn.receive(socket.read()[:])
socket.write(conn.take())
}
conn.alpn() // Some("h2")
conn.write(request[:])
// A server: the same three calls.
let server = @tls.Conn::server(@tls.Server::new(chain, Ecdsa(key), alpn=["h2"]), rand~)// The key schedule of RFC 8446 §7.1, one step at a time.
let early = @keys.early() // no PSK
let handshake = @keys.handshake(early[:], ecdhe[:]) // salted by ECDHE
let master = @keys.master(handshake[:])
let transcript = @keys.Transcript::new()
transcript.add(client_hello[:])
transcript.add(server_hello[:])
let secret = @keys.client_handshake(handshake[:], transcript.hash()[:])
let ok = @keys.finished_ok(secret[:], transcript.hash()[:], verify_data[:])Run moon run examples/tour for the whole surface in one go.
#Packages
| Specification | State | |
|---|---|---|
| wire | §3 integer widths and the frozen legacy_version | 0.2.0 |
| alert | §6 the alert protocol | 0.2.0 |
| keys | §7.1 key schedule, §4.4.1 transcript hash, §4.4.4 Finished | 0.1.0 |
| record | §5 record layer under any of the three suites, §7.3 traffic keys | 0.3.0 |
| ext | §4.2 extensions: supported_versions, supported_groups, signature_algorithms, key_share, ALPN, cookie, use_srtp | 0.4.0 |
| msg | §4 the handshake messages: ClientHello, ServerHello, EncryptedExtensions, Certificate, CertificateVerify, Finished | 0.4.0 |
| hs | Appendix A the state machine, §4.1.1 negotiation, §4.1.4 HelloRetryRequest, and the driver | 0.5.0 |
| dtls | RFC 9147 what datagrams change: both record shapes, record number encryption, the replay window, handshake fragmentation and reassembly, the ACK message, and the flight driver | 0.2.0 |
| tls | The connection: client and server, X25519, P-256 and P-384, the three suites, ECDSA, RSA-PSS and Ed25519 certificates, HelloRetryRequest, SNI, ALPN, KeyUpdate, close_notify; the server's chain judged by mooncred | 0.1.0 |
| srtp | RFC 5764 the SRTP protection profiles a DTLS handshake negotiates, and the keying material it exports for them | 0.1.0 |
msg is formats only. Which message may arrive next, and which parameters to pick, is the state machine's — that seam is what lets a tool read a ClientHello (an SNI router, a fingerprinter) without linking a handshake or a record layer.
ext says what is on the wire and nothing about what to pick from it: which group, which scheme, which version is the handshake's decision and lives in hs. quic_transport_parameters has a type code there and no codec — the payload is QUIC's (RFC 9000 §18), and reading somebody else's structure would be this library claiming to know it.
dtls derives its keys under dtls13, not tls13 (§5.9). Up to 0.9.0 it used the TLS prefix, which round-trips against itself and interoperates with nobody; pion/dtls's vectors caught it, and dtls/pion_wbtest.mbt now holds them.
dtls is everything a datagram forces and nothing else: the handshake messages, the key schedule and the extensions are unchanged, so they come from the packages beside it — its Driver runs hs's state machines, for either end, over flights instead of a stream. It has no clock: it answers what is still outstanding and what has to be acknowledged, and the caller decides when to resend, because §5.8's timers are a retransmission policy and choosing one for a caller is not a library's job.
srtp stops where TLS stops. It negotiates the profile and exports the keys; the RFC 3711 transform that encrypts an RTP packet is moonrtc's, because RTP is not TLS's business.
alert has no dependencies at all, on purpose: QUIC needs TLS's alerts without needing TLS's record layer, because RFC 9001 §5 replaces the record layer with QUIC's own packet protection.
#The digest is a parameter
RFC 8446 writes the whole ladder over Hash, the hash the negotiated cipher suite names. So every function here takes digest, and every output length follows from it:
@keys.early() // SHA-256, the suite RFC 8446 §9.1 makes mandatory
@keys.early(digest=Sha384) // 48 octets instead of 32, all the way down@keys.digest is the preset, and it is Sha256 because TLS_AES_128_GCM_SHA256 is the one implementation is required to provide.
#What is not here
Sockets — those are moonnet's. Cryptographic algorithms — those are mooncrypt's. QUIC's transport layer — that is moonquic, which borrows this handshake and reuses this key schedule verbatim (RFC 9001 §5.2). Not implemented yet: TLS 1.2, session resumption and 0-RTT, client certificates, and a DTLS connection on top of the dtls driver.
#Verification
The key schedule is checked against RFC 8446 §7.1 written out over Python's own HMAC — an implementation sharing no code with this one. The Early Secret for a zero PSK comes out 33ad0a1c…f170f92a, which is the value RFC 8448 publishes, so the ladder is anchored to the RFC's trace and not only to our own arithmetic.
The record layer is checked the same way, and one matching ciphertext covers the whole chain at once: the key and IV §7.3 derives, the nonce §5.3 builds from the sequence number, the trailing content type and padding of §5.2's inner plaintext, the five header octets chosen as the AEAD's additional data, and the AEAD itself.
DTLS has no RFC 8448 of its own — RFC 9147 publishes no traces — so its records are checked against the same kind of independent implementation, and one matching record again covers everything at once: the unified header's bits, the header as additional data, the nonce, and the AES-ECB mask that hides the sequence number.
The connection is checked against OpenSSL both ways: this client against openssl s_server under all four key types, all three suites and all three groups (36 handshakes), and openssl s_client against this server under the four key types and three suites (12), each verifying the chain, settling ALPN and carrying data; and this client against public servers with the Mozilla roots.
The gate is moon clean → moon fmt → moon check --target all --deny-warn → moon build --target all → moon test --target all, across wasm, wasm-gc, js and native.
#License
Apache-2.0.
Install
Download zipmoontls — the TLS 1.3 protocol state machine for MoonBit (RFC 8446) and DTLS 1.3 over datagrams (RFC 9147): record layers, handshake, key schedule and DTLS-SRTP keying, bytes in and events out. No sockets, no cryptography of its own.
tlstls13dtlsrfc8446rfc9147moonbit
Apache-2.0
Updated 9 hours ago
386 downloads