ssh_transport.cpp

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file ssh_transport.cpp
 * @brief SSH transport handshake - banner exchange and KEXINIT negotiation.
 */
 
#include "network_drivers/presentation/ssh/transport/ssh_transport.h"
#include "network_drivers/presentation/ssh/crypto/ssh_bignum.h"     // bn_*, SshBigNum
#include "network_drivers/presentation/ssh/crypto/ssh_curve25519.h" // ssh_x25519 (curve25519-sha256 KEX)
#include "network_drivers/presentation/ssh/crypto/ssh_ecdsa.h"      // ssh_ecdsa_p256_* (ecdsa-sha2-nistp256 host key)
#include "network_drivers/presentation/ssh/crypto/ssh_ed25519.h"    // ssh_ed25519 host-key sign
#include "network_drivers/presentation/ssh/crypto/ssh_rsa.h" // ssh_rsa_encode_pubkey/sign, ssh_host_pubkey, SSH_RSA_*
#include "network_drivers/presentation/ssh/crypto/ssh_sha256.h"
#include "network_drivers/presentation/ssh/transport/ssh_dh.h" // ssh_rng_fill(), ssh_dh[], ssh_dh_generate/derive_keys
#include "network_drivers/presentation/ssh/transport/ssh_packet.h" // SSH_MSG_KEXINIT, ssh_pkt[]
#include "services/clock.h"                                        // detws_millis() (re-key timer)
#if DETWS_ENABLE_PQC_KEX
#include "network_drivers/presentation/pqc/mlkem.h" // mlkem768_encaps (PQ/T hybrid KEX responder)
#endif
#if DETWS_ENABLE_SSH_ZLIB
#include "network_drivers/presentation/ssh/transport/ssh_comp.h" // s2c compression negotiation
#endif
#include <stdio.h> // snprintf (name-list assembly)
#include <string.h>
 
SshSession ssh_sess[MAX_SSH_CONNS];
 
// ---------------------------------------------------------------------------
// Negotiable algorithms. The server supports two KEX methods and two host-key
// types; cipher / MAC / compression are fixed. Negotiation is crypto-agnostic and
// steers toward whichever suite ssh_kex_set_prefer_rsa() selects (default: RSA/DH,
// hardware-accelerated on ESP32), while still advertising both suites so a client
// that supports only one still connects.
// ---------------------------------------------------------------------------
 
static const char *const KEX_DH = "diffie-hellman-group14-sha256";
static const char *const KEX_C25519 = "curve25519-sha256";
static const char *const KEX_C25519_LIBSSH = "curve25519-sha256@libssh.org"; // identical wire protocol
static const char *const KEX_ECDH_NISTP256 = "ecdh-sha2-nistp256";           // NIST P-256 ECDH (RFC 5656 §4)
#if DETWS_ENABLE_PQC_KEX
static const char *const KEX_MLKEM768 = "mlkem768x25519-sha256"; // PQ/T hybrid (ML-KEM-768 + X25519)
#endif
static const char *const HOSTKEY_RSA_SHA256 = "rsa-sha2-256";
static const char *const HOSTKEY_RSA_SHA512 = "rsa-sha2-512";
static const char HOSTKEY_ED[] = "ssh-ed25519";
static const char HOSTKEY_ECDSA[] = "ecdsa-sha2-nistp256";
static const char *const ALG_CIPHER = "aes256-ctr";
static const char *const ALG_CIPHER_GCM = "aes256-gcm@openssh.com";
// Advertised cipher preference (OpenSSH's default order): chacha20-poly1305@openssh.com (AEAD)
// first, aes256-gcm@openssh.com (AEAD, HW-accelerated) second, aes256-ctr (HW fallback) last.
static const char *const ALG_CIPHER_LIST = "chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes256-ctr";
static const char *const ALG_MAC = "hmac-sha2-256";
// Advertised MAC preference (aes256-ctr only; the chacha AEAD needs none): encrypt-then-MAC first
// (OpenSSH's default), then plain encrypt-and-MAC.
static const char *const ALG_MAC_LIST = "hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,"
                                        "hmac-sha2-256,hmac-sha2-512";
static const char *const ALG_COMP = "none";
#if DETWS_ENABLE_SSH_ZLIB
// Server->client compression preference: zlib@openssh.com (delayed, OpenSSH's default) first, then
// zlib (immediate), then none. Client->server stays "none" (ALG_COMP): see ssh_zlib.h.
static const char *const ALG_COMP_S2C = "zlib@openssh.com,zlib,none";
#else
static const char *const ALG_COMP_S2C = "none";
#endif
// RFC 8308 indicator a client sets in its kex_algorithms to request EXT_INFO.
static const char *const EXT_INFO_C = "ext-info-c";
 
// All SSH transport host-key/KEX state, owned by one instance (internal linkage): the runtime
// KEX preference (true = prefer the hardware-accelerated RSA/DH suite) and the optional
// ssh-ed25519 host key (the RSA host key is loaded via ssh_rsa). One named owner, cross-TU
// unreachable.
struct SshTransportCtx
{
    bool prefer_rsa = true;
    uint8_t ed_seed[32];
    uint8_t ed_pub[32];
    bool ed_have = false;
    uint8_t ecdsa_priv[SSH_ECDSA_P256_PRIV_LEN]; ///< P-256 host private scalar d.
    uint8_t ecdsa_pub[SSH_ECDSA_P256_PUB_LEN];   ///< P-256 host public point (0x04||X||Y).
    bool ecdsa_have = false;
};
static SshTransportCtx s_sshtr;
 
void ssh_kex_set_prefer_rsa(bool prefer)
{
    s_sshtr.prefer_rsa = prefer;
}
bool ssh_kex_prefer_rsa(void)
{
    return s_sshtr.prefer_rsa;
}
 
void ssh_hostkey_ed25519_set(const uint8_t seed[32])
{
    memcpy(s_sshtr.ed_seed, seed, 32);
    ssh_ed25519_pubkey(s_sshtr.ed_pub, s_sshtr.ed_seed);
    s_sshtr.ed_have = true;
}
bool ssh_hostkey_ed25519_available(void)
{
    return s_sshtr.ed_have;
}
void ssh_hostkey_ecdsa_set(const uint8_t priv[SSH_ECDSA_P256_PRIV_LEN])
{
    // Derive and cache the public point; reject an invalid scalar (leaves ecdsa_have false).
    if (!ssh_ecdsa_p256_pubkey(s_sshtr.ecdsa_pub, priv))
        return;
    memcpy(s_sshtr.ecdsa_priv, priv, SSH_ECDSA_P256_PRIV_LEN);
    s_sshtr.ecdsa_have = true;
}
bool ssh_hostkey_ecdsa_available(void)
{
    return s_sshtr.ecdsa_have;
}
static bool hostkey_rsa_available(void)
{
    return ssh_host_pubkey.loaded;
}
 
// Build the KEX / host-key advertise lists in preference order (RFC 4253 §7.1 name-
// lists), filtering host-key types to the keys we actually hold. server-sig-algs
// (RFC 8308) uses the same host-key ordering. Written into a caller buffer.
static void build_kex_list(char *out, size_t cap)
{
    const char *c1 = KEX_C25519;
    const char *c2 = KEX_C25519_LIBSSH;
    const char *dh = KEX_DH;
    const char *ec = KEX_ECDH_NISTP256; // NIST P-256 ECDH (RFC 5656)
#if DETWS_ENABLE_PQC_KEX
    // Post-quantum hybrid advertised first: a PQC-capable peer (OpenSSH 9.9+, which also lists it
    // first) negotiates it over classical X25519, closing the harvest-now-decrypt-later gap.
    const char *pq = KEX_MLKEM768;
    if (s_sshtr.prefer_rsa)
        snprintf(out, cap, "%s,%s,%s,%s,%s,ext-info-s", pq, dh, ec, c1, c2);
    else
        snprintf(out, cap, "%s,%s,%s,%s,%s,ext-info-s", pq, c1, c2, ec, dh);
#else
    if (s_sshtr.prefer_rsa)
        snprintf(out, cap, "%s,%s,%s,%s,ext-info-s", dh, ec, c1, c2);
    else
        snprintf(out, cap, "%s,%s,%s,%s,ext-info-s", c1, c2, ec, dh);
#endif
}
static void build_hostkey_list(char *out, size_t cap)
{
    // Both rsa-sha2-512 and rsa-sha2-256 are backed by the one "ssh-rsa" host key
    // (RFC 8332): advertise 512 before 256 (OpenSSH's order). Filter to keys we hold.
    const bool rsa = hostkey_rsa_available();
    const bool ed = ssh_hostkey_ed25519_available();
    const bool ec = ssh_hostkey_ecdsa_available();
    struct HostkeyCand
    {
        const char *name;
        bool ok;
    };
    HostkeyCand cand[4];
    if (s_sshtr.prefer_rsa)
    {
        cand[0] = {HOSTKEY_RSA_SHA512, rsa};
        cand[1] = {HOSTKEY_RSA_SHA256, rsa};
        cand[2] = {HOSTKEY_ECDSA, ec};
        cand[3] = {HOSTKEY_ED, ed};
    }
    else
    {
        cand[0] = {HOSTKEY_ED, ed};
        cand[1] = {HOSTKEY_ECDSA, ec};
        cand[2] = {HOSTKEY_RSA_SHA512, rsa};
        cand[3] = {HOSTKEY_RSA_SHA256, rsa};
    }
    out[0] = '\0';
    for (int k = 0; k < 4; k++)
    {
        if (!cand[k].ok)
            continue;
        size_t l = strnlen(out, cap);
        snprintf(out + l, cap - l, "%s%s", l ? "," : "", cand[k].name);
    }
}
 
// ---------------------------------------------------------------------------
// Byte-writer helpers
// ---------------------------------------------------------------------------
 
namespace
{
struct Writer
{
    uint8_t *p;
    size_t cap;
    size_t len;
    bool ok;
};
 
void w_bytes(Writer &w, const void *src, size_t n)
{
    if (!w.ok || w.len + n > w.cap)
    {
        w.ok = false;
        return;
    }
    memcpy(w.p + w.len, src, n); // NOSONAR - bound proven above; analyzer follows an infeasible path
    w.len += n;
}
 
void w_u8(Writer &w, uint8_t v)
{
    w_bytes(w, &v, 1);
}
 
void w_u32(Writer &w, uint32_t v)
{
    uint8_t b[4] = {(uint8_t)(v >> 24), (uint8_t)(v >> 16), (uint8_t)(v >> 8), (uint8_t)v};
    w_bytes(w, b, 4);
}
 
// Write an SSH name-list: uint32 length + comma-separated names.
void w_namelist(Writer &w, const char *list)
{
    uint32_t n = (uint32_t)strnlen(list, w.cap);
    w_u32(w, n);
    w_bytes(w, list, n);
}
 
// Write an SSH string: uint32 length + raw bytes.
void w_string(Writer &w, const uint8_t *data, size_t n)
{
    w_u32(w, (uint32_t)n);
    w_bytes(w, data, n);
}
 
// Write an SSH mpint from a fixed-width big-endian integer: strip leading zero
// bytes, prepend 0x00 if the top bit is set.
void w_mpint(Writer &w, const uint8_t *be, size_t len)
{
    size_t off = 0;
    while (off < len && be[off] == 0)
        off++;
    if (off == len)
    {
        w_u32(w, 0); // zero → empty string
        return;
    }
    bool pad = (be[off] & 0x80u) != 0;
    w_u32(w, (uint32_t)(len - off) + (pad ? 1u : 0u));
    if (pad)
        w_u8(w, 0x00);
    w_bytes(w, be + off, len - off);
}
} // namespace
 
// ---------------------------------------------------------------------------
// name-list membership test (RFC 4253 §7.1 - comma-separated, no spaces)
// ---------------------------------------------------------------------------
 
// Returns true if @p want appears as a complete element of the comma-separated
// list [list, list+len).
static bool namelist_contains(const uint8_t *list, uint32_t len, const char *want)
{
    size_t wl = strnlen(want, (size_t)len + 1);
    uint32_t start = 0;
    for (uint32_t i = 0; i <= len; i++)
    {
        if (i == len || list[i] == ',')
        {
            uint32_t elen = i - start;
            if (elen == wl && memcmp(list + start, want, wl) == 0)
                return true;
            start = i + 1;
        }
    }
    return false;
}
 
// One negotiation candidate: an algorithm name, the tag we store if it is chosen, and
// whether we can actually perform it (e.g. we hold the matching host key).
// A negotiation candidate: the wire name, the enum value it maps to, and whether we can perform it.
// Templated on the algorithm enum so each family (SshKexAlg / SshHostkeyAlg / cipher / mac / SshCompAlg)
// keeps its own type end to end - no type-erased int tag to cast into and back out of.
template <typename E> struct AlgCand
{
    const char *name;
    E tag;
    bool avail;
};
 
// Steer-to-preferred negotiation: pick the FIRST candidate (in OUR preference order) that the client
// also offers and that we can perform; write it to @p out and return true, or return false if none match.
template <typename E>
static bool negotiate_alg(const uint8_t *client_list, uint32_t nlen, const AlgCand<E> *cands, int n, E *out)
{
    for (int i = 0; i < n; i++)
        if (cands[i].avail && namelist_contains(client_list, nlen, cands[i].name))
        {
            *out = cands[i].tag;
            return true;
        }
    return false;
}
 
// ---------------------------------------------------------------------------
// Init
// ---------------------------------------------------------------------------
 
void ssh_transport_init(uint8_t i)
{
    if (i >= MAX_SSH_CONNS)
        return;
    SshSession *s = &ssh_sess[i];
    memset(s, 0, sizeof(*s));
    s->phase = SshPhase::SSH_PHASE_BANNER;
}
 
// ---------------------------------------------------------------------------
// Identification string exchange (RFC 4253 §4.2)
// ---------------------------------------------------------------------------
 
int ssh_transport_server_banner(uint8_t *out, size_t *out_len, size_t cap)
{
    size_t vlen = sizeof(SSH_SERVER_VERSION) - 1;
    if (vlen + 2 > cap)
        return -1;
    memcpy(out, SSH_SERVER_VERSION, vlen);
    out[vlen] = '\r';
    out[vlen + 1] = '\n';
    *out_len = vlen + 2;
    return 0;
}
 
int ssh_transport_recv_banner(uint8_t i, const uint8_t *data, size_t len, size_t *consumed)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshSession *s = &ssh_sess[i];
 
    size_t k = 0;
    while (k < len)
    {
        uint8_t c = data[k++];
        if (c == '\n')
        {
            // End of a line. Strip a trailing CR if present.
            uint16_t n = s->banner_len;
            if (n > 0 && s->banner_buf[n - 1] == '\r')
                n--;
 
            // RFC 4253 §4.2: the server may receive other lines before the
            // identification string; only the line starting with "SSH-" counts.
            if (n >= 4 && memcmp(s->banner_buf, "SSH-", 4) == 0)
            {
                if (n >= SSH_VERSION_MAX)
                    return -1;
                memcpy(s->v_c, s->banner_buf, n);
                s->v_c[n] = '\0';
                s->v_c_len = n;
                s->banner_len = 0;
                s->phase = SshPhase::SSH_PHASE_KEXINIT;
                *consumed = k;
                return 1;
            }
            // Not the SSH line - discard and keep scanning.
            s->banner_len = 0;
            continue;
        }
 
        if (s->banner_len >= SSH_VERSION_MAX)
            return -1; // line too long
        s->banner_buf[s->banner_len++] = c;
    }
 
    *consumed = k;
    return 0; // need more data
}
 
// ---------------------------------------------------------------------------
// KEXINIT (RFC 4253 §7.1)
// ---------------------------------------------------------------------------
 
int ssh_kexinit_build(uint8_t i, uint8_t *payload, size_t *len, size_t cap)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshSession *s = &ssh_sess[i];
 
    Writer w = {payload, cap, 0, true};
    w_u8(w, SSH_MSG_KEXINIT);
 
    uint8_t cookie[16];
    ssh_rng_fill(cookie, sizeof(cookie));
    w_bytes(w, cookie, sizeof(cookie));
 
    char kexlist[192];
    char hklist[48];
    build_kex_list(kexlist, sizeof(kexlist));
    build_hostkey_list(hklist, sizeof(hklist));
    w_namelist(w, kexlist);         // kex_algorithms (preference-ordered, + ext-info-s)
    w_namelist(w, hklist);          // server_host_key_algorithms (only keys we hold)
    w_namelist(w, ALG_CIPHER_LIST); // encryption c2s (chacha20-poly1305 preferred, aes256-ctr fallback)
    w_namelist(w, ALG_CIPHER_LIST); // encryption s2c
    w_namelist(w, ALG_MAC_LIST);    // mac c2s (used only with aes256-ctr; ignored for the AEAD cipher)
    w_namelist(w, ALG_MAC_LIST);    // mac s2c
    w_namelist(w, ALG_COMP);        // compression c2s (always none)
    w_namelist(w, ALG_COMP_S2C);    // compression s2c (zlib@openssh.com / zlib when built in)
    w_namelist(w, "");              // languages c2s
    w_namelist(w, "");              // languages s2c
    w_u8(w, 0);                     // first_kex_packet_follows = false
    w_u32(w, 0);                    // reserved
 
    if (!w.ok)
        return -1;
 
    // Retain a copy as I_S for the exchange hash.
    if (w.len > SSH_KEXINIT_S_MAX) // GCOVR_EXCL_LINE  the server's fixed algorithm lists never exceed SSH_KEXINIT_S_MAX
        return -1;                 // GCOVR_EXCL_LINE
    memcpy(s->i_s, payload, w.len);
    s->i_s_len = (uint16_t)w.len;
 
    *len = w.len;
    return 0;
}
 
// Read a name-list field at offset *off; set *list/*nlen to point into payload.
// Returns true on success and advances *off past the field.
static bool read_namelist(const uint8_t *p, size_t len, size_t *off, const uint8_t **list, uint32_t *nlen)
{
    if (*off + 4 > len)
        return false;
    uint32_t n = ((uint32_t)p[*off] << 24) | ((uint32_t)p[*off + 1] << 16) | ((uint32_t)p[*off + 2] << 8) |
                 (uint32_t)p[*off + 3];
    *off += 4;
    if (*off + n > len)
        return false;
    *list = p + *off;
    *nlen = n;
    *off += n;
    return true;
}
 
// Negotiate the key-exchange method from the client's kex_algorithms name-list, in our preference order
// (PQC hybrid first when enabled; RSA group first when prefer_rsa). false = no mutual method.
static bool negotiate_kex(const uint8_t *list, uint32_t nlen, SshKexAlg *out)
{
    AlgCand<SshKexAlg> kc[5];
    int nk = 0;
#if DETWS_ENABLE_PQC_KEX
    kc[nk++] = {KEX_MLKEM768, SshKexAlg::SSH_KEX_MLKEM768_X25519, true}; // hybrid first (PQC-preferred)
#endif
    if (s_sshtr.prefer_rsa)
    {
        kc[nk++] = {KEX_DH, SshKexAlg::SSH_KEX_DH_GROUP14, true};
        kc[nk++] = {KEX_ECDH_NISTP256, SshKexAlg::SSH_KEX_ECDH_NISTP256, true};
        kc[nk++] = {KEX_C25519, SshKexAlg::SSH_KEX_CURVE25519, true};
        kc[nk++] = {KEX_C25519_LIBSSH, SshKexAlg::SSH_KEX_CURVE25519, true};
    }
    else
    {
        kc[nk++] = {KEX_C25519, SshKexAlg::SSH_KEX_CURVE25519, true};
        kc[nk++] = {KEX_C25519_LIBSSH, SshKexAlg::SSH_KEX_CURVE25519, true};
        kc[nk++] = {KEX_ECDH_NISTP256, SshKexAlg::SSH_KEX_ECDH_NISTP256, true};
        kc[nk++] = {KEX_DH, SshKexAlg::SSH_KEX_DH_GROUP14, true};
    }
    return negotiate_alg(list, nlen, kc, nk, out);
}
 
// Negotiate the host-key algorithm, restricted to keys we actually hold. rsa-sha2-512/256 share the one
// RSA key (RFC 8332), ecdsa-sha2-nistp256 is a distinct P-256 key. false = no mutual algorithm.
static bool negotiate_hostkey(const uint8_t *list, uint32_t nlen, SshHostkeyAlg *out)
{
    const bool rsa = hostkey_rsa_available();
    const bool ed = ssh_hostkey_ed25519_available();
    const bool ec = ssh_hostkey_ecdsa_available();
    AlgCand<SshHostkeyAlg> hc[4];
    if (s_sshtr.prefer_rsa)
    {
        hc[0] = {HOSTKEY_RSA_SHA512, SshHostkeyAlg::SSH_HOSTKEY_RSA_SHA512, rsa};
        hc[1] = {HOSTKEY_RSA_SHA256, SshHostkeyAlg::SSH_HOSTKEY_RSA_SHA256, rsa};
        hc[2] = {HOSTKEY_ECDSA, SshHostkeyAlg::SSH_HOSTKEY_ECDSA_NISTP256, ec};
        hc[3] = {HOSTKEY_ED, SshHostkeyAlg::SSH_HOSTKEY_ED25519, ed};
    }
    else
    {
        hc[0] = {HOSTKEY_ED, SshHostkeyAlg::SSH_HOSTKEY_ED25519, ed};
        hc[1] = {HOSTKEY_ECDSA, SshHostkeyAlg::SSH_HOSTKEY_ECDSA_NISTP256, ec};
        hc[2] = {HOSTKEY_RSA_SHA512, SshHostkeyAlg::SSH_HOSTKEY_RSA_SHA512, rsa};
        hc[3] = {HOSTKEY_RSA_SHA256, SshHostkeyAlg::SSH_HOSTKEY_RSA_SHA256, rsa};
    }
    return negotiate_alg(list, nlen, hc, 4, out);
}
 
int ssh_kexinit_parse(uint8_t i, const uint8_t *payload, size_t len)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshSession *s = &ssh_sess[i];
 
    if (len < 1 + 16 || payload[0] != SSH_MSG_KEXINIT)
        return -1;
 
    // Retain a copy as I_C for the exchange hash.
    if (len > SSH_KEXINIT_MAX)
        return -1;
    memcpy(s->i_c, payload, len);
    s->i_c_len = (uint16_t)len;
 
    size_t off = 1 + 16; // skip msg type + 16-byte cookie
 
    const uint8_t *list;
    uint32_t nlen;
 
    // kex_algorithms: negotiate the KEX method in our preference order.
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    // RFC 8308: if the client offers ext-info-c we will send SSH_MSG_EXT_INFO.
    s->ext_info_c = namelist_contains(list, nlen, EXT_INFO_C);
    if (!negotiate_kex(list, nlen, &s->kex_alg))
        return -1; // no mutual KEX
    // server_host_key_algorithms: negotiate, restricted to keys we actually hold.
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    if (!negotiate_hostkey(list, nlen, &s->hostkey_alg))
        return -1; // no mutual host-key algorithm
    // encryption c2s / s2c: negotiate chacha20-poly1305@openssh.com or aes256-gcm@openssh.com (both
    // AEADs) or aes256-ctr, in that preference order.
    const AlgCand<decltype(SSH_CIPHER_AES256CTR)> cc[3] = {
        {"chacha20-poly1305@openssh.com", SSH_CIPHER_CHACHA20POLY1305, true},
        {ALG_CIPHER_GCM, SSH_CIPHER_AES256GCM, true},
        {ALG_CIPHER, SSH_CIPHER_AES256CTR, true}};
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    decltype(SSH_CIPHER_AES256CTR) c2s;
    decltype(SSH_CIPHER_AES256CTR) s2c;
    if (!negotiate_alg(list, nlen, cc, 3, &c2s))
        return -1;
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    if (!negotiate_alg(list, nlen, cc, 3, &s2c) || s2c != c2s) // require the same cipher both directions
        return -1;
    s->cipher_alg = c2s;
    // mac c2s / s2c: negotiated only for aes256-ctr (both AEAD ciphers carry their own MAC). Prefer
    // the encrypt-then-MAC variants (OpenSSH's default), require the same MAC both directions.
    const AlgCand<decltype(SSH_MAC_HMAC_SHA256)> mc[4] = {
        {"hmac-sha2-256-etm@openssh.com", SSH_MAC_HMAC_SHA256_ETM, true},
        {"hmac-sha2-512-etm@openssh.com", SSH_MAC_HMAC_SHA512_ETM, true},
        {ALG_MAC, SSH_MAC_HMAC_SHA256, true},
        {"hmac-sha2-512", SSH_MAC_HMAC_SHA512, true}};
    bool need_mac = (s->cipher_alg == SSH_CIPHER_AES256CTR);
    decltype(SSH_MAC_HMAC_SHA256) m_c2s = SSH_MAC_HMAC_SHA256;
    decltype(SSH_MAC_HMAC_SHA256) m_s2c = SSH_MAC_HMAC_SHA256;
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    if (need_mac && !negotiate_alg(list, nlen, mc, 4, &m_c2s))
        return -1;
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
    if (need_mac && (!negotiate_alg(list, nlen, mc, 4, &m_s2c) || m_s2c != m_c2s))
        return -1;
    s->mac_alg = m_c2s;
    // compression c2s: we only decompress "none" (client->server compression is not implemented).
    if (!read_namelist(payload, len, &off, &list, &nlen) || !namelist_contains(list, nlen, ALG_COMP))
        return -1;
    // compression s2c: negotiate zlib@openssh.com > zlib > none (server preference).
    if (!read_namelist(payload, len, &off, &list, &nlen))
        return -1;
#if DETWS_ENABLE_SSH_ZLIB
    {
        const AlgCand<SshCompAlg> compc[3] = {{"zlib@openssh.com", SshCompAlg::SSH_COMP_ZLIB_DELAYED, true},
                                              {"zlib", SshCompAlg::SSH_COMP_ZLIB, true},
                                              {"none", SshCompAlg::SSH_COMP_NONE, true}};
        SshCompAlg comp;
        if (!negotiate_alg(list, nlen, compc, 3, &comp))
            return -1;
        ssh_comp_set_s2c(i, comp);
    }
#else
    if (!namelist_contains(list, nlen, ALG_COMP))
        return -1;
#endif
 
    s->phase = SshPhase::SSH_PHASE_DH_INIT;
    return 0;
}
 
int ssh_extinfo_build(uint8_t *out, size_t *len, size_t cap)
{
    // byte SSH_MSG_EXT_INFO || uint32 nr-extensions || (string name, string value)*
    Writer w = {out, cap, 0, true};
    w_u8(w, SSH_MSG_EXT_INFO);
    w_u32(w, 1);                      // one extension
    w_namelist(w, "server-sig-algs"); // extension name
    // Accepted client public-key signature algorithms for userauth. All are always
    // verifiable (independent of which host key we hold); ordered by our preference so a
    // modern client picks the steered-to type. A client uses this to choose a key to offer.
    // Both RSA hashes are offered (rsa-sha2-512 first, RFC 8332); ssh_rsa_verify picks the
    // hash from the client's chosen algorithm name. ecdsa-sha2-nistp256 (RFC 5656) and
    // ssh-ed25519 are also verifiable, so all four are advertised in preference order.
    const char *siglist = s_sshtr.prefer_rsa ? "rsa-sha2-512,rsa-sha2-256,ecdsa-sha2-nistp256,ssh-ed25519"
                                             : "ssh-ed25519,ecdsa-sha2-nistp256,rsa-sha2-512,rsa-sha2-256";
    w_namelist(w, siglist); // value: accepted client-sig algorithms
    if (!w.ok)
        return -1;
    *len = w.len;
    return 0;
}
 
// ---------------------------------------------------------------------------
// Exchange hash H (RFC 4253 §8) - streamed into SHA-256, no large buffer.
// ---------------------------------------------------------------------------
 
// Hash a 4-byte big-endian length prefix.
static void hash_u32(SshSha256Ctx *ctx, uint32_t v)
{
    uint8_t b[4] = {(uint8_t)(v >> 24), (uint8_t)(v >> 16), (uint8_t)(v >> 8), (uint8_t)v};
    ssh_sha256_update(ctx, b, 4);
}
 
// Hash an SSH string: uint32 length + raw bytes.
static void hash_string(SshSha256Ctx *ctx, const uint8_t *data, size_t len)
{
    hash_u32(ctx, (uint32_t)len);
    ssh_sha256_update(ctx, data, len);
}
 
// Hash an SSH mpint from a fixed-width big-endian integer: strip leading zero
// bytes, prepend a 0x00 if the top bit is set (to keep it positive).
static void hash_mpint(SshSha256Ctx *ctx, const uint8_t *be, size_t len)
{
    size_t off = 0;
    while (off < len && be[off] == 0)
        off++;
    if (off == len)
    {
        // Value is zero → mpint is an empty string.
        hash_u32(ctx, 0);
        return;
    }
    bool pad = (be[off] & 0x80u) != 0;
    uint32_t mlen = (uint32_t)(len - off) + (pad ? 1u : 0u);
    hash_u32(ctx, mlen);
    if (pad)
    {
        uint8_t zero = 0;
        ssh_sha256_update(ctx, &zero, 1);
    }
    ssh_sha256_update(ctx, be + off, len - off);
}
 
// Method-neutral exchange hash. The client/server public values are hashed as SSH
// strings for an ECDH KEX (Q_C, Q_S; RFC 8731) or the PQ/T hybrid (C_INIT, S_REPLY), or as mpints
// for a finite-field DH KEX (e, f; RFC 4253 §8). K is an mpint for the classical methods but a plain
// string for the hybrid (its K is a fixed-length HASH output, RFC 4251 §5 / draft-ietf-sshm). cpub/
// spub are big-endian, right-aligned in their buffers, so hash_mpint / hash_string produce the
// canonical minimal encoding.
static int compute_exchange_hash(uint8_t i, bool pub_is_string, const uint8_t *cpub, size_t cpub_len,
                                 const uint8_t *spub, size_t spub_len, const uint8_t *k_be, size_t k_len,
                                 const uint8_t *ks, size_t ks_len, uint8_t out[SSH_SHA256_DIGEST_LEN], bool k_is_string)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshSession *s = &ssh_sess[i];
 
    static const char *const v_s = SSH_SERVER_VERSION;
 
    SshSha256Ctx ctx;
    ssh_sha256_init(&ctx);
    hash_string(&ctx, (const uint8_t *)s->v_c, s->v_c_len);                  // V_C
    hash_string(&ctx, (const uint8_t *)v_s, sizeof(SSH_SERVER_VERSION) - 1); // V_S
    hash_string(&ctx, s->i_c, s->i_c_len);                                   // I_C
    hash_string(&ctx, s->i_s, s->i_s_len);                                   // I_S
    hash_string(&ctx, ks, ks_len);                                           // K_S
    if (pub_is_string)
    {
        hash_string(&ctx, cpub, cpub_len); // Q_C
        hash_string(&ctx, spub, spub_len); // Q_S
    }
    else
    {
        hash_mpint(&ctx, cpub, cpub_len); // e
        hash_mpint(&ctx, spub, spub_len); // f
    }
    if (k_is_string)
        hash_string(&ctx, k_be, k_len); // hybrid: K is a fixed-length HASH output (RFC 4251 string)
    else
        hash_mpint(&ctx, k_be, k_len); // classical: K is an mpint
    ssh_sha256_final(&ctx, out);
    return 0;
}
 
int ssh_kex_exchange_hash(uint8_t i, const uint8_t *e_be, const uint8_t *f_be, const uint8_t *k_be, const uint8_t *ks,
                          size_t ks_len, uint8_t out[SSH_SHA256_DIGEST_LEN])
{
    return compute_exchange_hash(i, false, e_be, 256, f_be, 256, k_be, 256, ks, ks_len, out, false);
}
 
// ---------------------------------------------------------------------------
// KEXDH (RFC 4253 §8)
// ---------------------------------------------------------------------------
 
int ssh_kexdh_parse_init(const uint8_t *payload, size_t len, uint8_t e_be[256])
{
    if (len < 1 + 4 || payload[0] != SSH_MSG_KEXDH_INIT)
        return -1;
 
    uint32_t n = ((uint32_t)payload[1] << 24) | ((uint32_t)payload[2] << 16) | ((uint32_t)payload[3] << 8) |
                 (uint32_t)payload[4];
    if ((size_t)5 + n > len)
        return -1;
 
    const uint8_t *m = payload + 5;
    size_t off = 0;
    while (off < n && m[off] == 0) // strip sign/leading-zero bytes
        off++;
    size_t vlen = n - off;
    if (vlen > 256)
        return -1; // e exceeds 2048 bits
 
    memset(e_be, 0, 256);
    memcpy(e_be + (256 - vlen), m + off, vlen);
    return 0;
}
 
int ssh_kexdh_build_reply(const uint8_t *ks, size_t ks_len, const uint8_t *f_be, const uint8_t *sig, size_t sig_len,
                          uint8_t *out, size_t *out_len, size_t cap)
{
    Writer w = {out, cap, 0, true};
    w_u8(w, SSH_MSG_KEXDH_REPLY);
    w_string(w, ks, ks_len); // K_S
    w_mpint(w, f_be, 256);   // f
 
    // signature = string( string("rsa-sha2-256") || string(sig) )
    uint32_t inner = 4 + 12 + 4 + (uint32_t)sig_len;
    w_u32(w, inner);
    w_string(w, (const uint8_t *)"rsa-sha2-256", 12);
    w_string(w, sig, sig_len);
 
    if (!w.ok)
        return -1;
    *out_len = w.len;
    return 0;
}
 
// Parse SSH_MSG_KEX_ECDH_INIT (msg 30, shares the number with KEXDH_INIT):
// byte(30) || string(Q_C). Q_C must be exactly 32 bytes for X25519 (RFC 8731).
static int parse_ecdh_init(const uint8_t *payload, size_t len, uint8_t qc[32])
{
    if (len < 1 + 4 || payload[0] != SSH_MSG_KEXDH_INIT)
        return -1;
    uint32_t n = ((uint32_t)payload[1] << 24) | ((uint32_t)payload[2] << 16) | ((uint32_t)payload[3] << 8) |
                 (uint32_t)payload[4];
    if (n != 32 || (size_t)5 + n > len)
        return -1;
    memcpy(qc, payload + 5, 32);
    return 0;
}
 
// Parse SSH_MSG_KEX_ECDH_INIT for ecdh-sha2-nistp256 (RFC 5656 §4): byte(30) || string(Q_C),
// where Q_C is the 65-byte uncompressed client point 0x04 || X || Y.
static int parse_ecdh_init_p256(const uint8_t *payload, size_t len, uint8_t qc[SSH_ECDSA_P256_PUB_LEN])
{
    if (len < 1 + 4 || payload[0] != SSH_MSG_KEXDH_INIT)
        return -1;
    uint32_t n = ((uint32_t)payload[1] << 24) | ((uint32_t)payload[2] << 16) | ((uint32_t)payload[3] << 8) |
                 (uint32_t)payload[4];
    if (n != SSH_ECDSA_P256_PUB_LEN || (size_t)5 + n > len)
        return -1;
    memcpy(qc, payload + 5, SSH_ECDSA_P256_PUB_LEN);
    return 0;
}
 
// Encode the server host-key blob K_S for the negotiated host-key algorithm.
//   rsa-sha2-256/512     → "ssh-rsa" blob (ssh_rsa_encode_pubkey)
//   ssh-ed25519          → string("ssh-ed25519") || string(pub32)          (RFC 8709 §4)
//   ecdsa-sha2-nistp256  → string(name) || string("nistp256") || string(Q) (RFC 5656 §3.1)
static int encode_hostkey(uint8_t i, uint8_t *ks, size_t *ks_len, size_t cap)
{
    if (ssh_sess[i].hostkey_alg == SshHostkeyAlg::SSH_HOSTKEY_ED25519)
    {
        Writer w = {ks, cap, 0, true};
        w_string(w, (const uint8_t *)HOSTKEY_ED, sizeof(HOSTKEY_ED) - 1);
        w_string(w, s_sshtr.ed_pub, 32);
        if (!w.ok)     // GCOVR_EXCL_LINE  the ed25519 blob (~51B) always fits the RSA-sized ks buffer
            return -1; // GCOVR_EXCL_LINE
        *ks_len = w.len;
        return 0;
    }
    if (ssh_sess[i].hostkey_alg == SshHostkeyAlg::SSH_HOSTKEY_ECDSA_NISTP256)
    {
        Writer w = {ks, cap, 0, true};
        w_string(w, (const uint8_t *)HOSTKEY_ECDSA, sizeof(HOSTKEY_ECDSA) - 1);
        w_string(w, (const uint8_t *)"nistp256", 8); // RFC 5656 curve identifier
        w_string(w, s_sshtr.ecdsa_pub, SSH_ECDSA_P256_PUB_LEN);
        if (!w.ok)     // GCOVR_EXCL_LINE  the ecdsa blob (~104B) always fits the RSA-sized ks buffer
            return -1; // GCOVR_EXCL_LINE
        *ks_len = w.len;
        return 0;
    }
    return ssh_rsa_encode_pubkey(ks, ks_len, cap);
}
 
// Sign the exchange hash H with the negotiated host key. Writes the raw signature (no
// SSH framing) plus its algorithm name; the caller wraps it as the signature blob.
static int sign_hash(uint8_t i, const uint8_t H[SSH_SHA256_DIGEST_LEN], uint8_t *sig, size_t *sig_len, size_t sig_cap,
                     const char **sig_name)
{
    if (ssh_sess[i].hostkey_alg == SshHostkeyAlg::SSH_HOSTKEY_ED25519)
    {
        if (sig_cap < 64) // GCOVR_EXCL_LINE  the caller's sig buffer is SSH_RSA_SIG_BYTES (256) >= 64
            return -1;    // GCOVR_EXCL_LINE
        ssh_ed25519_sign(sig, H, SSH_SHA256_DIGEST_LEN, s_sshtr.ed_seed);
        *sig_len = 64;
        *sig_name = HOSTKEY_ED; // "ssh-ed25519"
        return 0;
    }
    if (ssh_sess[i].hostkey_alg == SshHostkeyAlg::SSH_HOSTKEY_ECDSA_NISTP256)
    {
        uint8_t raw[SSH_ECDSA_P256_SIG_LEN]; // r || s (32 + 32)
        if (!ssh_ecdsa_p256_sign(raw, H, SSH_SHA256_DIGEST_LEN, s_sshtr.ecdsa_priv))
            return -1; // GCOVR_EXCL_LINE  key is available (negotiated) and sign is infallible for a valid d
        // ECDSA signature blob is mpint(r) || mpint(s) (RFC 5656 §3.1.2).
        Writer w = {sig, sig_cap, 0, true};
        w_mpint(w, raw, SSH_ECDSA_P256_COORD_LEN);
        w_mpint(w, raw + SSH_ECDSA_P256_COORD_LEN, SSH_ECDSA_P256_COORD_LEN);
        if (!w.ok)     // GCOVR_EXCL_LINE  the mpint blob (~74B) always fits the 256B sig buffer
            return -1; // GCOVR_EXCL_LINE
        *sig_len = w.len;
        *sig_name = HOSTKEY_ECDSA; // "ecdsa-sha2-nistp256"
        return 0;
    }
    // rsa-sha2-512 and rsa-sha2-256 share the one "ssh-rsa" key; the negotiated
    // algorithm only chooses the signature hash (RFC 8332).
    const bool sha512 = (ssh_sess[i].hostkey_alg == SshHostkeyAlg::SSH_HOSTKEY_RSA_SHA512);
    const SshRsaHash rh = sha512 ? SshRsaHash::SHA512 : SshRsaHash::SHA256;
    if (sig_cap < SSH_RSA_SIG_BYTES ||
        ssh_rsa_sign(H, SSH_SHA256_DIGEST_LEN, rh, sig) != 0) // GCOVR_EXCL_LINE  sig buffer is 256B and the negotiated
        return -1; // GCOVR_EXCL_LINE  RSA key is loaded (available), so neither the size nor the sign can fail
    *sig_len = SSH_RSA_SIG_BYTES;
    *sig_name = sha512 ? HOSTKEY_RSA_SHA512 : HOSTKEY_RSA_SHA256;
    return 0;
}
 
// Assemble SSH_MSG_KEXDH_REPLY (== KEX_ECDH_REPLY / KEX_HYBRID_REPLY, msg 31):
//   byte(31) || string(K_S) || (mpint f | string Q_S | string S_REPLY) || string( string(sig_name) || string(sig) )
static int build_kex_reply(uint8_t i, const uint8_t *ks, size_t ks_len, const uint8_t *spub, size_t spub_len,
                           const char *sig_name, const uint8_t *sig, size_t sig_len, uint8_t *out, size_t *out_len,
                           size_t cap)
{
    Writer w = {out, cap, 0, true};
    w_u8(w, SSH_MSG_KEXDH_REPLY);
    w_string(w, ks, ks_len); // K_S
    if (ssh_sess[i].kex_alg == SshKexAlg::SSH_KEX_DH_GROUP14)
        w_mpint(w, spub, spub_len); // f (mpint)
    else
        w_string(w, spub, spub_len); // Q_S (curve25519) or S_REPLY (hybrid), a raw string
    uint32_t nl = (uint32_t)strnlen(sig_name, w.cap);
    w_u32(w, 4 + nl + 4 + (uint32_t)sig_len); // signature blob length
    w_string(w, (const uint8_t *)sig_name, nl);
    w_string(w, sig, sig_len);
    if (!w.ok)
        return -1;
    *out_len = w.len;
    return 0;
}
 
int ssh_kex_generate(uint8_t i)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshKexAlg a = ssh_sess[i].kex_alg;
    bool curve = (a == SshKexAlg::SSH_KEX_CURVE25519);
#if DETWS_ENABLE_PQC_KEX
    curve = curve || (a == SshKexAlg::SSH_KEX_MLKEM768_X25519); // the hybrid's classical half is X25519
#endif
    if (curve)
    {
        // X25519 ephemeral: random 32-byte scalar, public = X25519(scalar, base point).
        ssh_rng_fill(ssh_sess[i].ecdh_sk, 32);
        ssh_x25519_base(ssh_sess[i].ecdh_pk, ssh_sess[i].ecdh_sk);
        return 0;
    }
    if (a == SshKexAlg::SSH_KEX_ECDH_NISTP256)
    {
        // P-256 ECDH ephemeral: a random scalar d in [1, n) stored in ecdh_sk. The 65-byte public
        // point Q_S = d*G is re-derived in ssh_kexdh_handle (avoids a curve-specific session field).
        // Re-draw on the negligible chance a raw 32-byte value is 0 or >= n (an invalid P-256 scalar).
        uint8_t qtmp[SSH_ECDSA_P256_PUB_LEN];
        for (int t = 0; t < 8; t++)
        {
            ssh_rng_fill(ssh_sess[i].ecdh_sk, 32);
            if (ssh_ecdsa_p256_pubkey(qtmp, ssh_sess[i].ecdh_sk))
                return 0;
        }
        return -1; // GCOVR_EXCL_LINE  a random 32-byte scalar is a valid P-256 key with overwhelming probability
    }
    return ssh_dh_generate(i);
}
 
#if DETWS_ENABLE_PQC_KEX
// mlkem768x25519-sha256 (draft-ietf-sshm-mlkem-hybrid-kex): from the client's SSH_MSG_KEX_HYBRID_INIT
// (byte 30 || string C_INIT, C_INIT = ek(1184) || Q_C(32)), ML-KEM-Encaps to the peer's key and X25519
// against Q_C, then combine K = SHA256(K_PQ || K_CL). Writes S_REPLY = ciphertext(1088) || Q_S(32) and
// the 32-byte shared secret. Returns 0, or -1 on a malformed C_INIT, bad ML-KEM key, or low-order point.
static int hybrid_mlkem_x25519(uint8_t i, const uint8_t *payload, size_t len, uint8_t s_reply[MLKEM768_CT_BYTES + 32],
                               uint8_t k_out[32])
{
    if (len < 1 + 4 || payload[0] != SSH_MSG_KEXDH_INIT)
        return -1;
    uint32_t n = ((uint32_t)payload[1] << 24) | ((uint32_t)payload[2] << 16) | ((uint32_t)payload[3] << 8) |
                 (uint32_t)payload[4];
    if (n != MLKEM768_EK_BYTES + 32 || (size_t)5 + n > len)
        return -1;
    const uint8_t *ek = payload + 5;                     // C_PK2: ML-KEM-768 encapsulation key
    const uint8_t *qc = payload + 5 + MLKEM768_EK_BYTES; // C_PK1: client X25519 public
 
    uint8_t m[32];
    ssh_rng_fill(m, sizeof(m));
    uint8_t k_pq[32];
    bool ok = mlkem768_encaps(ek, m, s_reply, k_pq); // ciphertext -> s_reply[0..1087]
    ssh_wipe(m, sizeof(m));
    if (!ok)
        return -1; // malformed encapsulation key (FIPS 203 modulus check)
 
    uint8_t k_cl[32];
    ssh_x25519(k_cl, ssh_sess[i].ecdh_sk, qc);
    uint8_t zacc = 0;
    for (int b = 0; b < 32; b++)
        zacc |= k_cl[b];
    if (zacc == 0) // low-order X25519 point (RFC 7748 §6.1)
    {
        ssh_wipe(k_pq, sizeof(k_pq));
        ssh_wipe(k_cl, sizeof(k_cl));
        return -1;
    }
    memcpy(s_reply + MLKEM768_CT_BYTES, ssh_sess[i].ecdh_pk, 32); // S_PK1: server X25519 public
 
    SshSha256Ctx hc;
    ssh_sha256_init(&hc);
    ssh_sha256_update(&hc, k_pq, sizeof(k_pq)); // K = SHA256(K_PQ || K_CL) (RFC 9370 concat combiner)
    ssh_sha256_update(&hc, k_cl, sizeof(k_cl));
    ssh_sha256_final(&hc, k_out);
    ssh_wipe(k_pq, sizeof(k_pq));
    ssh_wipe(k_cl, sizeof(k_cl));
    return 0;
}
#endif
 
int ssh_kexdh_handle(uint8_t i, const uint8_t *payload, size_t len, uint8_t *reply_out, size_t *reply_len, size_t cap)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    SshSession *s = &ssh_sess[i];
 
    // 1. Shared secret K + the two public values, per negotiated KEX method. cpub_p / spub_p point at
    //    the values hashed into H (local buffers for DH / curve, the larger C_INIT / S_REPLY blobs for
    //    the hybrid); k_hash / k_hash_len select K's encoding (an mpint for DH / curve, a fixed 32-byte
    //    string for the hybrid). k_be holds K right-aligned so hash_mpint / the KDF strip to minimal.
    uint8_t k_be[256];
    memset(k_be, 0, sizeof(k_be));
    uint8_t cpub[256];
    uint8_t spub[256]; // client / server public value (right-aligned) for DH / curve25519
    const uint8_t *cpub_p = cpub;
    const uint8_t *spub_p = spub;
    size_t cpub_len = 256;
    size_t spub_len = 256;
    const uint8_t *k_hash = k_be;
    size_t k_hash_len = 256;
    bool pub_is_string = false;
    bool k_is_string = false;
#if DETWS_ENABLE_PQC_KEX
    uint8_t s_reply[MLKEM768_CT_BYTES + 32]; // hybrid S_REPLY = ciphertext(1088) || Q_S(32)
#endif
 
    if (s->kex_alg == SshKexAlg::SSH_KEX_CURVE25519)
    {
        // curve25519-sha256 (RFC 8731): K = X25519(sk, Q_C); Q_C/Q_S hashed as strings.
        uint8_t qc[32];
        uint8_t kk[32];
        if (parse_ecdh_init(payload, len, qc) != 0)
            return -1;
        ssh_x25519(kk, s->ecdh_sk, qc);
        // Reject a low-order client point (all-zero shared secret) - RFC 7748 §6.1.
        uint8_t zacc = 0;
        for (int b = 0; b < 32; b++)
            zacc |= kk[b];
        if (zacc == 0)
        {
            ssh_wipe(kk, sizeof(kk));
            return -1;
        }
        memcpy(k_be + (256 - 32), kk, 32);
        memcpy(cpub, qc, 32);
        memcpy(spub, s->ecdh_pk, 32);
        cpub_len = spub_len = 32;
        pub_is_string = true;
        ssh_wipe(kk, sizeof(kk));
    }
#if DETWS_ENABLE_PQC_KEX
    else if (s->kex_alg == SshKexAlg::SSH_KEX_MLKEM768_X25519)
    {
        // mlkem768x25519-sha256: K = SHA256(K_PQ || K_CL); C_INIT / S_REPLY and K hashed as strings.
        if (hybrid_mlkem_x25519(i, payload, len, s_reply, k_be + (256 - 32)) != 0)
            return -1;
        cpub_p = payload + 5; // C_INIT (ek || Q_C), hashed verbatim as a string
        cpub_len = MLKEM768_EK_BYTES + 32;
        spub_p = s_reply; // S_REPLY (ciphertext || Q_S)
        spub_len = MLKEM768_CT_BYTES + 32;
        k_hash = k_be + (256 - 32); // K is exactly 32 bytes, string-encoded (not mpint)
        k_hash_len = 32;
        pub_is_string = true;
        k_is_string = true;
    }
#endif
    else if (s->kex_alg == SshKexAlg::SSH_KEX_ECDH_NISTP256)
    {
        // ecdh-sha2-nistp256 (RFC 5656 §4): K = X(d_S * Q_C). Q_C/Q_S are 65-byte point strings; K an mpint.
        uint8_t qc[SSH_ECDSA_P256_PUB_LEN];
        if (parse_ecdh_init_p256(payload, len, qc) != 0)
            return -1;
        uint8_t qs[SSH_ECDSA_P256_PUB_LEN];
        uint8_t kk[SSH_ECDSA_P256_COORD_LEN];
        // Re-derive our ephemeral public Q_S, then the shared secret. ssh_ecdsa_p256_ecdh validates
        // Q_C is on-curve and the product is not the identity (RFC 5656 §4 point checks).
        if (!ssh_ecdsa_p256_pubkey(qs, s->ecdh_sk) || !ssh_ecdsa_p256_ecdh(kk, qc, s->ecdh_sk))
            return -1;
        memcpy(k_be + (256 - SSH_ECDSA_P256_COORD_LEN), kk, SSH_ECDSA_P256_COORD_LEN);
        memcpy(cpub, qc, SSH_ECDSA_P256_PUB_LEN);
        memcpy(spub, qs, SSH_ECDSA_P256_PUB_LEN);
        cpub_len = SSH_ECDSA_P256_PUB_LEN;
        spub_len = SSH_ECDSA_P256_PUB_LEN;
        pub_is_string = true;
        ssh_wipe(kk, sizeof(kk));
    }
    else
    {
        // diffie-hellman-group14-sha256 (RFC 4253 §8): K = e^y mod p; e/f are mpints.
        uint8_t e_be[256];
        if (ssh_kexdh_parse_init(payload, len, e_be) != 0)
            return -1;
        SshBigNum e;
        bn_from_bytes(&e, e_be, 256);
        if (bn_dh_validate(&e) != 0)
            return -1;
        SshBigNum K;
        bn_expmod_group14(&K, &e, &ssh_dh[i].y);
        bn_to_bytes(k_be, &K);
        ssh_wipe(&K, sizeof(K));
        memcpy(cpub, e_be, 256);
        bn_to_bytes(spub, &ssh_dh[i].f);
    }
 
    // 2. Host-key blob K_S (per negotiated host-key algorithm).
    uint8_t ks[SSH_RSA_PUBKEY_BLOB_MAX];
    size_t ks_len = 0;
    if (encode_hostkey(i, ks, &ks_len, sizeof(ks)) != 0) // GCOVR_EXCL_LINE  encode_hostkey cannot fail: ks is
    {                                 // GCOVR_EXCL_LINE  SSH_RSA_PUBKEY_BLOB_MAX, sized for either blob
        ssh_wipe(k_be, sizeof(k_be)); // GCOVR_EXCL_LINE
        return -1;                    // GCOVR_EXCL_LINE
    }
 
    // 3. Exchange hash H; capture the session id on the first KEX.
    uint8_t H[SSH_SHA256_DIGEST_LEN];
    compute_exchange_hash(i, pub_is_string, cpub_p, cpub_len, spub_p, spub_len, k_hash, k_hash_len, ks, ks_len, H,
                          k_is_string);
    if (!s->have_session_id)
    {
        memcpy(s->session_id, H, SSH_SHA256_DIGEST_LEN);
        s->have_session_id = true;
    }
 
    // 4. Sign H with the negotiated host key (rsa-sha2-512/256 or ssh-ed25519).
    uint8_t sig[SSH_RSA_SIG_BYTES]; // 256 bytes: fits an RSA-2048 sig and a 64-byte ed25519 sig
    size_t sig_len = 0;
    const char *sig_name = nullptr;
    if (sign_hash(i, H, sig, &sig_len, sizeof(sig), &sig_name) != 0) // GCOVR_EXCL_LINE  sign_hash cannot fail here:
    {                                                                // GCOVR_EXCL_LINE  256B sig buffer + a loaded key
        ssh_wipe(k_be, sizeof(k_be));                                // GCOVR_EXCL_LINE
        return -1;                                                   // GCOVR_EXCL_LINE
    }
 
    // 5. Assemble the reply, then derive the six session keys (id fixed at first KEX's H).
    if (build_kex_reply(i, ks, ks_len, spub_p, spub_len, sig_name, sig, sig_len, reply_out, reply_len, cap) != 0)
    {
        ssh_wipe(k_be, sizeof(k_be));
        return -1;
    }
    ssh_dh_derive_keys_sid(i, k_be, H, s->session_id, s->cipher_alg, s->mac_alg, k_is_string);
    ssh_wipe(k_be, sizeof(k_be));
 
    s->phase = SshPhase::SSH_PHASE_NEWKEYS;
    return 0;
}
 
void ssh_newkeys_sent(uint8_t i)
{
    if (i >= MAX_SSH_CONNS)
        return;
    // We have emitted our SSH_MSG_NEWKEYS: our outbound direction is now encrypted (RFC 4253 sec 7.3).
    ssh_pkt[i].enc_out = true;
#if DETWS_ENABLE_SSH_ZLIB
    // "zlib" (non-delayed) starts its s2c (outbound) stream here; idempotent, so a re-key does not restart it.
    ssh_comp_on_newkeys(i);
#endif
}
 
void ssh_newkeys_complete(uint8_t i)
{
    if (i >= MAX_SSH_CONNS)
        return;
    // We have received the peer's SSH_MSG_NEWKEYS: our inbound direction is now encrypted. Both directions
    // are keyed once we get here (the server always sends its NEWKEYS first), so the KEX is complete.
    ssh_pkt[i].enc_in = true;
    ssh_pkt[i].kex_active = false;
    // On the first KEX advance to the service phase; on a re-key the connection
    // is already authenticated, so resume the open (channel) phase.
    ssh_sess[i].phase = ssh_sess[i].authed ? SshPhase::SSH_PHASE_OPEN : SshPhase::SSH_PHASE_SERVICE;
    // Reset the re-key timer: the volume/time budget is measured from this completed KEX.
    ssh_sess[i].last_kex_ms = detws_millis();
}
 
bool ssh_rekey_needed(uint8_t i)
{
    if (i >= MAX_SSH_CONNS)
        return false;
    return ssh_pkt[i].seq_no_send >= SSH_REKEY_PACKET_THRESHOLD || ssh_pkt[i].seq_no_recv >= SSH_REKEY_PACKET_THRESHOLD;
}
 
bool ssh_rekey_due(uint32_t seq_send, uint32_t seq_recv, uint32_t elapsed_ms, uint32_t pkt_threshold,
                   uint32_t time_threshold_ms)
{
    if (seq_send >= pkt_threshold || seq_recv >= pkt_threshold)
        return true; // volume budget (RFC 4253 sec 9: ~1 GB)
    if (time_threshold_ms && elapsed_ms >= time_threshold_ms)
        return true; // time budget (~1 hour)
    return false;
}
 
int ssh_transport_begin_rekey(uint8_t i, uint8_t *out, size_t *out_len, size_t cap)
{
    if (i >= MAX_SSH_CONNS)
        return -1;
    // Fresh server KEXINIT (re-stores I_S for the new exchange hash).
    if (ssh_kexinit_build(i, out, out_len, cap) != 0)
        return -1;
    // New ephemeral for forward secrecy across the re-key (re-generated for the finally
    // negotiated method once the peer's KEXINIT arrives; see the KEXINIT dispatch).
    if (ssh_kex_generate(i) != 0) // GCOVR_EXCL_LINE  i < MAX_SSH_CONNS is checked above and ssh_kex_generate only
        return -1;                // GCOVR_EXCL_LINE  fails for i >= MAX_SSH_CONNS
    ssh_sess[i].phase = SshPhase::SSH_PHASE_KEXINIT;
    return 0;
}