Sourcing rationale

The "DJB-first" principle applies where it does not compromise interoperability: X25519 for key exchange and ChaCha20-Poly1305 as the preferred cipher suite. AES-GCM and ECDSA P-256 are included because RFC 8446 §9.1 mandates TLS_AES_128_GCM_SHA256 and because real-world certificate chains use ECDSA P-256 or RSA.

Primitive reference

TweetNaCl

TweetNaCl (~700 lines, public domain) is imported for X25519 and Ed25519 only. TweetNaCl uses XSalsa20, not IETF ChaCha20 -- the two are different constructions. For TLS 1.3's TLS_CHACHA20_POLY1305_SHA256, the IETF ChaCha20 variant (RFC 8439, 96-bit nonce) is used separately.

TweetNaCl functions used:

• crypto_scalarmult_curve25519 -- X25519 ECDH

• crypto_sign_ed25519 / crypto_sign_ed25519_open -- Ed25519

• crypto_hash_sha512 -- SHA-512 (internal to Ed25519)

• crypto_verify_32 -- constant-time 32-byte comparison

All other TweetNaCl functions (secretbox, box, stream) are unused and compiled out.

BearSSL extracts

BearSSL is a TLS 1.2 library; only its low-level cryptographic components are extracted. BearSSL's higher-level components (x509_minimal.c, ASN.1 codecs, PEM handling, TLS engine) are not imported -- the X.509/PKI and TLS 1.3 layers are self-written.

Extracted components:

• aes_ct_ctr.c -- AES in counter mode, constant-time (cache-safe)

• ghash_ctmul32.c -- GHASH for GCM, constant-time

• ec_p256_m15.c / ec_p384_m15.c -- P-256 and P-384 field arithmetic

• ecdsa_i15_sign_asn1.c / ecdsa_i15_vrfy_asn1.c -- ECDSA operations

• rsa_i15_pkcs1_vrfy.c -- RSA verification

BearSSL is MIT licensed. Original copyright headers are preserved in all extracted files under src/litls/bearssl/. See CREDITS.

Certificate parsing

litls_x509_parse(der, der_len, info) extracts from a DER-encoded X.509 certificate:

Key types: LITLS_KEY_ECDSA_P256 (1), LITLS_KEY_RSA (2), LITLS_KEY_ECDSA_P384 (3), LITLS_KEY_ED25519 (4).

Signature algorithms: LITLS_SIG_ECDSA_SHA256 (1), LITLS_SIG_ECDSA_SHA384 (2), LITLS_SIG_RSA_SHA256 (3), LITLS_SIG_RSA_SHA384 (4), LITLS_SIG_RSA_SHA512 (5), LITLS_SIG_ED25519 (6).

Chain validation

litls_x509_verify_chain() validates a certificate chain (leaf-first):

1. Parse each certificate via litls_x509_parse().

2. For each cert i, verify its signature against cert i+1's public key.

3. For the final cert, try all trust anchors by signature verification (not CN matching -- handles cross-signed intermediates correctly).

4. Check validity periods against a caller-provided timestamp (now=0 skips time validation).

Error codes:

Limits: max 8 certificates in chain, max 256 trust anchors.

litls_x509_load_anchors(pem_data, pem_len, anchors, max) loads trust anchors from a PEM CA bundle, parsing each certificate to extract its public key.

PEM handling

CSR generation

litls_csr_generate(params, der_out, der_cap) creates a DER-encoded PKCS#10 CSR using ECDSA P-256 + SHA-256, for ACME certificate issuance. The CSR structure is hand-encoded DER (one domain + SANs). Max output: 4096 bytes.

Cipher suites

All three are advertised in ClientHello. The server selects from the intersection.

Key exchange

Only X25519 (NamedGroup 0x001D) is offered in the key_share extension. If a server rejects X25519 with HelloRetryRequest, the HRR is honored only if it requests X25519 again (error otherwise). Cookie extension (up to 512 bytes) is supported for HRR flows.

No P-256 key exchange -- only P-256 certificate verification.

Signature algorithms

Advertised in ClientHello and accepted in CertificateVerify (RFC 8446 §4.2.3 forbids RSASSA-PKCS1-v1_5 for TLS 1.3 handshake signatures, so it is not offered):

RSA PKCS#1 v1.5 with SHA-256/384/512 is still accepted as an X.509 chain signature algorithm in litls_x509_verify_chain -- it is only forbidden in TLS 1.3 CertificateVerify.

Client handshake

ClientHello
  - supported_versions: [TLS 1.3]
  - supported_groups: [x25519]
  - key_share: [x25519: ephemeral_public_key]
  - signature_algorithms: [ecdsa_secp256r1_sha256, rsa_pss_rsae_sha256,
                            ed25519]
  - server_name: <SNI hostname>
  - cipher_suites: [0x1303, 0x1301, 0x1302]

  ServerHello
    - parse key_share (server X25519 public key)
    - derive shared secret via X25519(ephemeral_priv, server_pub)
    - derive handshake_secret via HKDF key schedule

  {EncryptedExtensions}

  {Certificate}
    - decode certificate chain
    - validate against trust anchors
    - extract server public key

  {CertificateVerify}
    - verify signature over transcript hash

  {Finished}
    - verify HMAC over transcript

ClientFinished
  - send client Finished

  derive application traffic secrets
  CONNECTED

Server handshake

  ClientHello
    - parse cipher suites (select best)
    - parse key_shares (expect x25519)
    - parse SNI, select cert/key
    - generate ephemeral X25519 keypair
    - derive shared secret, handshake_secret

ServerHello (cipher suite, server X25519 key_share)
{EncryptedExtensions}
{Certificate} (leaf + chain)
{CertificateVerify} (sign transcript with server private key)
{Finished} (HMAC over transcript)

  ClientFinished
    - verify client Finished

  derive application traffic secrets
  CONNECTED

Key schedule

RFC 8446 §7.1 key schedule, using HKDF-SHA256 (or SHA384 for AES-256-GCM):

early_secret      = HKDF-Extract(0, PSK=0)
derived_secret    = Derive-Secret(early_secret, "derived", "")
handshake_secret  = HKDF-Extract(derived_secret, DHE)
client_hs_traffic = Derive-Secret(handshake_secret, "c hs traffic", CH..SH)
server_hs_traffic = Derive-Secret(handshake_secret, "s hs traffic", CH..SH)
...
master_secret     = HKDF-Extract(Derive-Secret(handshake_secret, "derived", ""), 0)
client_ap_traffic = Derive-Secret(master_secret, "c ap traffic", CH..SF)
server_ap_traffic = Derive-Secret(master_secret, "s ap traffic", CH..SF)

AEAD keys and IVs are derived per §7.3:

key = HKDF-Expand-Label(traffic_secret, "key", "", key_len)
iv  = HKDF-Expand-Label(traffic_secret, "iv",  "", 12)

Record nonce = per-record sequence number XOR'd with IV (§5.3).

Post-handshake messages

• NewSessionTicket: Received and silently discarded (no resumption).

• KeyUpdate: Not implemented. A received KeyUpdate is a fatal error.

• close_notify: Sent and honored on shutdown.

Non-blocking I/O integration

The TLS state machine is fully non-blocking. litls_tls13_handshake_step() returns one of:

LEV's C core (lev_core.c) drives the state machine via starttls_init() and starttls_step(). The Lua coroutine loop in lev.lua yields on WANT_READ/WANT_WRITE and resumes when epoll signals readiness. See LEV for the Lua-facing TLS API.

litls.core module

The litls.core module exposes all LITLS primitives to Lua. Most application code should use the higher-level crypto module or LEV's TLS integration instead of calling litls.core directly.

Base64

Random

Hashes

HMAC

HKDF (RFC 5869)

ChaCha20 / Poly1305

AEAD

X25519

Ed25519

Ed25519 / X25519 key conversion

ECDSA P-256

ECDSA P-384

RSA verify

Hex helpers

X.509 / PEM / CSR

TLS 1.3 key schedule (for testing)

Constants

Higher-level modules

crypto module (src/crypto/crypto.lua): High-level wrapper over litls.core (via the crypto.core C binding). Provides SHA-1, SHA-256, HMAC, Base64/Base64url, ECC P-256 key management (keygen, sign, verify, JWK save/load), Ed25519 (keygen, sign, verify), CSR generation, PEM encoding, and X.509 certificate parsing. Most application code should use crypto rather than litls.core directly.

LEV TLS integration (src/lev/): TLS connections are created via lev.connect() with a tls config table, or sock:starttls() for server-side upgrade. The TLS handshake runs non-blocking inside the LEV event loop. See LEV for the full TLS API.

To be done

• Mutual TLS (server-side): Server-side CertificateRequest sending and client certificate verification is not yet implemented. Client-side mTLS (sending client certificates when requested by the server) is supported for ECDSA P-256 and Ed25519 client keys.