alktls/docs/architecture/server.md

status, last_updated

status	last_updated
draft	2026-09-10

alktls — Server side

TlsServerConfig and its resolvers: the server-side TLS setup, extracted from alknet (crates/alknet-tls/src/server.rs) and ported per the ADRs. Statuses of the decisions referenced here: see open-questions.md and the ADR index in overview.md.

TlsServerConfig

The central server-side type. Built once from a TlsIdentity + ALPN list, shared across transports via Arc (not Clone — it holds the ACME task's JoinHandle).

pub struct TlsServerConfig {
    rustls_config: rustls::ServerConfig,   // Clone-safe — Arc internally
    acme_handle: Option<tokio::task::JoinHandle<()>>,  // acme-gated
}

impl TlsServerConfig {
    pub async fn new(identity: &TlsIdentity, alpns: &[Vec<u8>])
        -> Result<Self, TlsError>;

    #[cfg(feature = "noq")]
    pub fn for_noq(&self) -> Result<noq::ServerConfig, TlsError>;

    #[cfg(feature = "tcp")]
    pub fn for_tcp_tls(&self) -> tokio_rustls::TlsAcceptor;

    pub fn rustls_config(&self) -> &rustls::ServerConfig;
}

Construction dispatch (ADR-001's identity model):

• X509 { cert, key } — loads the chain + key from disk (pem.rs), with_single_cert.
• RawKey(Ed25519SecretKey) — RawKeyCertResolver presents the Ed25519 key as an RFC 7250 raw public key server cert.
• SelfSigned — generate_self_signed_cert() (rcgen), in-memory.
• Acme { domains, cache_dir, directory, contact } — the ACME path (below). Server-only: on the client path it is a config error.

Behavior-preservation invariants

These are load-bearing (ADR-001); an implementation that omits any of them compiles but silently changes TLS behavior. Each is asserted by test (ADR-006):

• max_early_data_size = u32::MAX on every server config path — enables 0-RTT / early data. Omitting it silently breaks 0-RTT clients.
• rustls::crypto::aws_lc_rs::default_provider() as the crypto provider on all paths (alknet ADR-084). Never ring, never the process-default provider, without a new ADR.
• AcceptAnyCertVerifier::supported_verify_schemes() returns ED25519 + ECDSA P-256/P-384 + RSA PSS (SHA256/384/512) + RSA PKCS1 (SHA256/384/512) — nine schemes, verbatim, pinned by an exact-list integration test.
• acme-tls/1 ALPN append for the ACME path only, done by the crate, not the caller (alknet ADR-027 §7).
• Non-empty root store — the client CA path merges webpki-roots when the platform store is empty (see client.md).

AcceptAnyCertVerifier

The server-side client-cert verifier: request-but-don't-require. It asks for a client cert (X.509 or RFC 7250 raw key) so the caller can extract the fingerprint via peer_identity(), but does not require one and does not verify the presented cert against a CA. The fingerprint is matched against peer records by the auth layer (IdentityProvider::resolve_from_fingerprint) outside this crate — the TLS crate hands over the fingerprint string; peer resolution is not a TLS concern (ADR-005).

Server-side only: this must not be reused as a client-side ServerCertVerifier — client-side verification is alknet ADR-034's selection matrix (see client.md).

RawKeyCertResolver

Presents an Ed25519SecretKey as an RFC 7250 raw public key server certificate: the SPKI DER (Ed25519 OID + 32-byte key) is the "cert", only_raw_public_keys() == true, and the signing key is the shared Ed25519SigningKey helper (signing.rs).

The ACME path

For TlsIdentity::Acme, new (feature acme):

1. Builds rustls_acme::AcmeConfig — the upstream builder, distinct from TlsError::AcmeConfig (domains, DirCache cache dir, directory URL from AcmeDirectory, contacts).
2. Wires state.resolver() as the cert resolver into the server config.
3. Appends acme-tls/1 to the ALPN list (TLS-ALPN-01 challenge).
4. Spawns the event-loop task (tokio::spawn) matching EventOk/EventError variants to tracing logs, and returns immediately — it does not await the first certificate.

Lifecycle semantics:

• The returned config is usable right away; handshakes fail transiently until the first order completes (or a cached cert deploys).
• Order errors log at warn! and retry inside rustls-acme; the task exits only when the event stream ends.
• The task is detached: the stored JoinHandle is never aborted; ACME runs for the process lifetime (OQ-TLS-06 resolved detached-only; a shutdown() surface would be additive later if the rewrite's graceful-shutdown design wants one).
• One state machine per domain — never spawn a second ACME task for an already-served domain (duplicate orders = Let's Encrypt rate-limit risk + cert-cache divergence). This is why TlsServerConfig is not Clone.
• Runtime errors are stream events, not TlsError variants (ADR-002's scope boundary). TlsError::AcmeConfig covers config-mismatch mistakes ("ACME feature not enabled but Acme configured" — and on the client path, Acme used for client auth), not runtime failures.

What the server side does NOT do

• No accept loop: for_tcp_tls() yields a TlsAcceptor; the TcpListener::accept → TlsAcceptor::accept → dispatch loop belongs to the caller (alknet ADR-083 — the endpoint takes no TLS config; the assembly layer builds configs and transports).
• No ALPN policy: the ALPN list is a parameter (the assembly layer filters per endpoint type — alknet ADR-086 §3); the crate appends only acme-tls/1 on the ACME path.
• No handshake: verifier selection and handshake outcomes on the server side are AcceptAnyCertVerifier + the caller's fingerprint extraction; a rejected handshake is the transport's error, not TlsError.
• No peer resolution: the extracted fingerprint string goes to the caller; PeerEntry/AuthPolicy live in the auth layer.

References

• overview.md — the index; client.md — the client side
• alknet crates/tls/README.md §Architecture — the full server-side spec this doc mirrors
• ADR-001 (invariants), ADR-002 (TlsError), ADR-003 (for_noq), ADR-004 (accessors), ADR-005 (identity types), ADR-006 (modules, tests)