TLS 1.3 and DTLS 1.3 for MoonBit.
// 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. The key is any PEM file `openssl` writes.
let chain = @x509.pems(cert_pem) // leaf first
let config = @tls.Server::new(chain, @x509.PrivateKey::pem(key_pem), alpn=["h2"])
let server = @tls.Conn::server(config, rand~)test {
let early = @keys.early() // no PSK: the zero secret
let shared = b"\x8b\xd4\x05\x4f\xb5\x5b\x9d\x63\xfd\xfb\xac\xf9\xf0\x4b\x9f\x0d\x35\xe6\xd6\x3f\x53\x75\x63\xef\xd4\x62\x72\x90\x0f\x89\x49\x2d"
let handshake = @keys.handshake(early[:], shared[:]) // salted by the key exchange
let transcript = @keys.Transcript::new()
transcript.add(b"\x01\x00\x00\x00"[:]) // a ClientHello, for the shape of it
let secret = @keys.client_handshake(handshake[:], transcript.hash()[:])
assert_eq(
@base16.encode(secret[:]),
"ab4fc9e2370723165814c074381ab62cbb2c32fd421b15db6910f5df5b1756a3",
)
}test {
let suite = @record.Aes128Gcm
let secret = @base16.decode("ab4fc9e2370723165814c074381ab62cbb2c32fd421b15db6910f5df5b1756a3")
let writer = @record.Cipher::new(secret[:], suite~)
let record = writer.seal(@record.Handshake, b"hello"[:])
assert_eq(@base16.encode(record[:]), "1703030016ea041db0127f9d1812962e71632919c00bfbe245872d")
// The same secret on the other side opens it: the content type moved inside, and came back.
let reader = @record.Cipher::new(secret[:], suite~)
let (kind, content) = reader.open(record[:])
assert_eq(kind, @record.Handshake)
assert_eq(content, b"hello")
}// A DTLS 1.3 client: datagrams in and out, and a clock you supply.
let conn = @dtls.Conn13::client(config, "example.com", rand~, now~, wall~)
socket.send(conn.take())
while !conn.is_connected() {
conn.receive(socket.recv()[:], now~=monotonic_ms())
socket.send(conn.take())
if conn.deadline() is Some(due) && monotonic_ms() >= due {
conn.tick(now~=monotonic_ms())
}
}| Specification | State | |
|---|---|---|
| wire | §3 integer widths, the frozen legacy_version, Reader, the cursor every decoder reads through, and Refused, what a decoder raises when the octets are not the structure their own lengths describe | 0.3.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 five suites, §7.3 traffic keys; TLS 1.2's suite table and record protection | 0.3.0 |
| ext | §4.2 extensions: server_name, 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, fragmentation and reassembly, the ACK message and the flight driver — and Conn13 and Conn12, the two connections over it, with RFC 6347's DTLS 1.2 record layer beside 1.3's | 0.3.0 |
| tls | The connection: client and server, X25519MLKEM768, X25519, P-256, P-384, P-521 and X448, and SecP256r1MLKEM768, SecP384r1MLKEM1024, ML-KEM alone and the RFC 7919 groups on request, the five suites of §B.4 (the two AES-CCM ones on request), ECDSA, RSA, RSASSA-PSS, Ed25519 and ML-DSA certificates and more than one per server, HelloRetryRequest, SNI, ALPN, KeyUpdate, close_notify, middlebox compatibility mode, declined 0-RTT data read past; pre-shared keys a caller supplies, in either PSK mode; certificate compression under zlib, brotli or zstd, either direction; TLS 1.2 beside 1.3 and the session resumption, client certificates, renegotiation and stapling that come with them; 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 |
@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| Case | What happens |
|---|---|
| TLS 1.2 renegotiation, server side | The server's HelloRequest is answered and the second handshake starts, but OpenSSL rejects the first record sealed under the new keys — bad record mac, or a provider error with ChaCha20. The two ends of this library agree with each other, which is why nothing noticed. A client cannot start one at all: Conn::renegotiate is the server's HelloRequest. |
| 0-RTT, this library as the client | The early traffic secret is not the problem and neither is the record: against s_server -early_data -max_early_data 4096, OpenSSL's own CLIENT_EARLY_TRAFFIC_SECRET for the connection is the same 32 octets this client derives, and the early record decrypts under it with AAD = 17 03 03 || length in an independent check. What OpenSSL does is decline the ticket before it gets that far: with -max_early_data it issues its anti-replay tickets, which are a 32-octet session id kept on the server, and this client's resumption is refused under those whether or not it carries early data — a full handshake, resumed=0, and no early secret derived at all. The same client resumes the 192-octet stateless ticket that a server without -max_early_data hands out. The other direction is in the matrix: s_client -sess_in -early_data against this server answers Reused and Early data was accepted. |
| SRP against OpenSSL, six cases | OpenSSL 3's SRP is deprecated and does not work in either role: s_server -srpvfile segfaults, against its own s_client too, and s_client -srpuser derives a premaster that differs from this server's while every value on the wire — N, g, the salt, A and B — agrees, with and without extended master secret. tlslite-ng's client and server complete SRP and SRP-RSA handshakes with this library both ways and carry a line, so the SRP cases that count are those. |
| 0-RTT, this library as the server | Covered: the server: 0-RTT accepted case, OpenSSL's client against this server, s_client -sess_in … -early_data. The client's own half of the same handshake is refused by OpenSSL's anti-replay tickets, above. |
| # | Server | Scripts it is for |
|---|---|---|
| 0 | an RSA certificate and every group | the general one, ecdhe-brainpool-curves, obsolete-curves |
| 1 | an ECDSA P-256 certificate, and one on each of P-384, P-521 and the three brainpool curves | minerva, ecdsa-support |
| 2 | an Ed25519 certificate | eddsa |
| 3 | an RSA certificate that asks for a client certificate, under a root this run issues | the six that answer a handshake CertificateRequest, handed -c/-k and -s |
| 4 | every TLS version and every TLS 1.2 suite | symetric-ciphers, version-negotiation, 0rtt-garbage |
| 5 | a server that sends the first KeyUpdate, for the request that names it | keyupdate-from-server |
| 7 | an RSASSA-PSS certificate | rsapss-signatures |
| 8 | a server that asks for a client certificate once the connection is open | post-handshake-auth |
| 9 | a server that accepts one external pre-shared key, in either PSK mode | psk_ke, psk_dhe_ke |
| 10 | a server that hands out tickets and takes one back under either mode | session-resumption |
| 11 | the five groups a script is told about, and no others | no-unknown-groups |
| 12 | a server that compresses its Certificate, and judges a malformed offer as §3 does | certificate-compression |
| 13 | the same, and a request for a client certificate, which may come compressed too | client-certificate-compression |
| 14 | TLS 1.2 and below, and no TLS 1.3 at all | non-support |
| 15 | a server that answers every line with the same line | lengths |
| Scripts | What happens |
|---|---|
| connection-abort | 140 of its 150 conversations pass. One probe, repeated ten times, sends a line and then reads a NewSessionTicket before it closes; this server issues none, because the client offered no psk_key_exchange_modes and RFC 8446 §4.2.9 says "Servers SHOULD NOT send NewSessionTicket with tickets that are not compatible with the advertised modes". A client that keeps no session store has nothing to resume with, and a test of that rule (resume_test.mbt) pins the silence. Sending one anyway would pass the probe and contradict both. |
| ecdsa-brainpool-in-certificate-verify | No conversation reaches a server: the script is handed a brainpool client key on its command line, and tlslite-ng cannot read one (SyntaxError: Unknown curve in parsePEMKey). The end this library controls — a brainpool certificate in a CertificateVerify — is what ecdsa-support and ecdhe-brainpool-curves cover, and both pass. |
Install
Download zipTLS 1.3 and DTLS 1.3 for MoonBit.