New post-quantum kex: ML-KEM, and three hybrids of it.

As standardised by NIST in FIPS 203, this is a lattice-based
post-quantum KEM.

Very vaguely, the idea of it is that your public key is a matrix A and
vector t, and the private key is the knowledge of how to decompose t
into two vectors with all their coefficients small, one transformed by
A relative to the other. Encryption of a binary secret starts by
turning each bit into one of two maximally separated residues mod a
prime q, and then adding 'noise' based on the public key in the form
of small increments and decrements mod q, again with some of the noise
transformed by A relative to the rest. Decryption uses the knowledge
of t's decomposition to align the two sets of noise so that the
_large_ changes (which masked the secret from an eavesdropper) cancel
out, leaving only a collection of small changes to the original secret
vector. Then the vector of input bits can be recovered by assuming
that those accumulated small pieces of noise haven't concentrated in
any particular residue enough to push it more than half way to the
other of its possible starting values.

A weird feature of it is that decryption is not a true mathematical
inverse of encryption. The assumption that the noise doesn't get large
enough to flip any bit of the secret is only probabilistically valid,
not a hard guarantee. In other words, key agreement can fail, simply
by getting particularly unlucky with the distribution of your random
noise! However, the probability of a failure is very low - less than
2^-138 even for ML-KEM-512, and gets even smaller with the larger
variants.

An awkward feature for our purposes is that the matrix A, containing a
large number of residues mod the prime q=3329, is required to be
constructed by a process of rejection sampling, i.e. generating random
12-bit values and throwing away the out-of-range ones. That would be a
real pain for our side-channel testing system, which generally handles
rejection sampling badly (since it necessarily involves data-dependent
control flow and timing variation). Fortunately, the matrix and the
random seed it was made from are both public: the matrix seed is
transmitted as part of the public key, so it's not necessary to try to
hide it. Accordingly, I was able to get the implementation to pass
testsc by means of not varying the matrix seed between runs, which is
justified by the principle of testsc that you vary the _secrets_ to
ensure timing is independent of them - and the matrix seed isn't a
secret, so you're allowed to keep it the same.

The three hybrid algorithms, defined by the current Internet-Draft
draft-kampanakis-curdle-ssh-pq-ke, include one hybrid of ML-KEM-768
with Curve25519 in exactly the same way we were already hybridising
NTRU Prime with Curve25519, and two more hybrids of ML-KEM with ECDH
over a NIST curve. The former hybrid interoperates with the
implementation in OpenSSH 9.9; all three interoperate with the fork
'openssh-oqs' at github.com/open-quantum-safe/openssh, and also with
the Python library AsyncSSH.

config.c

@@ -578,6 +578,8 @@ static void kexlist_handler(dlgcontrol *ctrl, dlgparam *dlg,
             { "RSA-based key exchange",             KEX_RSA },
             { "ECDH key exchange",                  KEX_ECDH },
             { "NTRU Prime / Curve25519 hybrid kex", KEX_NTRU_HYBRID },
+            { "ML-KEM / Curve25519 hybrid kex",     KEX_MLKEM_25519_HYBRID },
+            { "ML-KEM / NIST ECDH hybrid kex",      KEX_MLKEM_NIST_HYBRID },
             { "-- warn below here --",              KEX_WARN }
         };
 

crypto/CMakeLists.txt

@@ -24,6 +24,7 @@ add_sources_from_current_dir(crypto
   mac.c
   mac_simple.c
   md5.c
+  mlkem.c
   mpint.c
   ntru.c
   openssh-certs.c

crypto/kex-hybrid.c

@@ -36,6 +36,10 @@ static char *hybrid_description(const ssh_kex *kex)
     const char *classical_name;
     if (alg->classical_alg == &ssh_ec_kex_curve25519)
         classical_name = "Curve25519";
+    else if (alg->classical_alg == &ssh_ec_kex_nistp256)
+        classical_name = "NIST P256";
+    else if (alg->classical_alg == &ssh_ec_kex_nistp384)
+        classical_name = "NIST P384";
     else
         unreachable("don't have a name for this classical alg");
 
@@ -320,3 +324,65 @@ static const ssh_kex *const ntru_hybrid_list[] = {
 const ssh_kexes ssh_ntru_hybrid_kex = {
     lenof(ntru_hybrid_list), ntru_hybrid_list,
 };
+
+static const hybrid_alg ssh_mlkem768_curve25519_hybrid = {
+    .combining_hash = &ssh_sha256,
+    .pq_alg = &ssh_mlkem768,
+    .classical_alg = &ssh_ec_kex_curve25519,
+    .reformat = reformat_mpint_be_32,
+};
+
+static const ssh_kex ssh_mlkem768_curve25519 = {
+    .name = "mlkem768x25519-sha256",
+    .main_type = KEXTYPE_ECDH,
+    .hash = &ssh_sha256,
+    .ecdh_vt = &hybrid_selector_vt,
+    .extra = &ssh_mlkem768_curve25519_hybrid,
+};
+
+static const ssh_kex *const mlkem_curve25519_hybrid_list[] = {
+    &ssh_mlkem768_curve25519,
+};
+
+const ssh_kexes ssh_mlkem_curve25519_hybrid_kex = {
+    lenof(mlkem_curve25519_hybrid_list), mlkem_curve25519_hybrid_list,
+};
+
+static const hybrid_alg ssh_mlkem768_p256_hybrid = {
+    .combining_hash = &ssh_sha256,
+    .pq_alg = &ssh_mlkem768,
+    .classical_alg = &ssh_ec_kex_nistp256,
+    .reformat = reformat_mpint_be_32,
+};
+
+static const ssh_kex ssh_mlkem768_p256 = {
+    .name = "mlkem768nistp256-sha256",
+    .main_type = KEXTYPE_ECDH,
+    .hash = &ssh_sha256,
+    .ecdh_vt = &hybrid_selector_vt,
+    .extra = &ssh_mlkem768_p256_hybrid,
+};
+
+static const hybrid_alg ssh_mlkem1024_p384_hybrid = {
+    .combining_hash = &ssh_sha384,
+    .pq_alg = &ssh_mlkem1024,
+    .classical_alg = &ssh_ec_kex_nistp384,
+    .reformat = reformat_mpint_be_48,
+};
+
+static const ssh_kex ssh_mlkem1024_p384 = {
+    .name = "mlkem1024nistp384-sha384",
+    .main_type = KEXTYPE_ECDH,
+    .hash = &ssh_sha384,
+    .ecdh_vt = &hybrid_selector_vt,
+    .extra = &ssh_mlkem1024_p384_hybrid,
+};
+
+static const ssh_kex *const mlkem_nist_hybrid_list[] = {
+    &ssh_mlkem1024_p384,
+    &ssh_mlkem768_p256,
+};
+
+const ssh_kexes ssh_mlkem_nist_hybrid_kex = {
+    lenof(mlkem_nist_hybrid_list), mlkem_nist_hybrid_list,
+};

crypto/mlkem.h

@@ -0,0 +1,89 @@
+/*
+ * Internal functions for the ML-KEM cryptosystem, exposed in a header
+ * that is expected to be included only by mlkem.c and test programs.
+ */
+
+#ifndef PUTTY_CRYPTO_MLKEM_H
+#define PUTTY_CRYPTO_MLKEM_H
+
+typedef struct mlkem_params mlkem_params;
+
+extern const mlkem_params mlkem_params_512;
+extern const mlkem_params mlkem_params_768;
+extern const mlkem_params mlkem_params_1024;
+
+/*
+ * ML-KEM key generation.
+ *
+ * The official spec gives two APIs for this function: an outer one
+ * that invents random data from an implicit PRNG parameter, and an
+ * inner one that takes the randomness as explicit input for running
+ * test vectors.
+ *
+ * To make side-channel testing easier, I introduce a third API inside
+ * the latter. The spec's "inner" function takes a parameter 'd'
+ * containing 32 bytes of randomness, which it immediately expands
+ * into a 64-byte hash and then uses the two halves of that hash for
+ * different purposes. My even-more-inner function expects the caller
+ * to have done that hashing already, and to present the two 32-byte
+ * half-hashes rho and sigma separately.
+ *
+ * Rationale: it would be difficult to make the keygen running time
+ * independent of rho, becase the required technique for constructing
+ * a matrix from rho uses rejection sampling, so timing will depend on
+ * how many samples were rejected. Happily, it's also not _necessary_
+ * to make the timing independent of rho, because rho is part of the
+ * _public_ key, so it's sent in clear over the wire anyway. So for
+ * testsc purposes, it's convenient to regard rho as fixed and vary
+ * sigma, so that the timing variations due to rho don't show up as
+ * failures in the test.
+ *
+ * Inputs: 'd', 'z', 'rho' and 'sigma' are all 32-byte random strings.
+ *
+ * Return: the encryption and decryption keys are written to the two
+ * provided BinarySinks.
+ */
+void mlkem_keygen(
+    BinarySink *ek, BinarySink *dk, const mlkem_params *params);
+void mlkem_keygen_internal(
+    BinarySink *ek, BinarySink *dk, const mlkem_params *params,
+    const void *d, const void *z);
+void mlkem_keygen_rho_sigma(
+    BinarySink *ek, BinarySink *dk, const mlkem_params *params,
+    const void *rho, const void *sigma, const void *z);
+
+/*
+ * ML-KEM key encapsulation, with only two forms, the outer (random)
+ * and inner (for test vectors) versions from the spec.
+ *
+ * Inputs: the encryption key from keygen. 'm' should be a 32-byte
+ * random string if provided.
+ *
+ * Returns: if successful, returns true, and writes to the two
+ * BinarySinks a ciphertext to send to the other side, and our copy of
+ * the output shared secret k. If failure, returns false, and the
+ * strbuf pointers aren't filled in at all.
+ */
+bool mlkem_encaps(BinarySink *ciphertext, BinarySink *kout,
+                  const mlkem_params *params, ptrlen ek);
+bool mlkem_encaps_internal(BinarySink *ciphertext, BinarySink *kout,
+                           const mlkem_params *params, ptrlen ek,
+                           const void *m);
+
+/*
+ * ML-KEM key decapsulation. This doesn't use any randomness, so even
+ * the official spec only presents one version of it. (Actually it
+ * defines two functions, but the outer one adds nothing over the
+ * inner one.)
+ *
+ * Inputs: the decryption key from keygen, and the ciphertext output
+ * from encapsulation.
+ *
+ * Returns: false on validation failure, and true otherwise
+ * (regardless of whether the ciphertext was implicitly rejected). The
+ * shared secret k is written to the provided BinarySink.
+ */
+bool mlkem_decaps(BinarySink *k, const mlkem_params *params,
+                  ptrlen dk, ptrlen c);
+
+#endif /* PUTTY_CRYPTO_MLKEM_H */

putty.h

@@ -388,6 +388,8 @@ enum {
     KEX_RSA,
     KEX_ECDH,
     KEX_NTRU_HYBRID,
+    KEX_MLKEM_25519_HYBRID,
+    KEX_MLKEM_NIST_HYBRID,
     KEX_MAX
 };
 

settings.c

@@ -30,6 +30,8 @@ static const struct keyvalwhere ciphernames[] = {
  * in sync with those. */
 static const struct keyvalwhere kexnames[] = {
     { "ntru-curve25519",    KEX_NTRU_HYBRID, -1, +1 },
+    { "mlkem-curve25519",   KEX_MLKEM_25519_HYBRID, KEX_NTRU_HYBRID, +1 },
+    { "mlkem-nist",         KEX_MLKEM_NIST_HYBRID, KEX_MLKEM_25519_HYBRID, +1 },
     { "ecdh",               KEX_ECDH,       -1, +1 },
     /* This name is misleading: it covers both SHA-256 and SHA-1 variants */
     { "dh-gex-sha1",        KEX_DHGEX,      -1, -1 },

ssh.h

@@ -1242,6 +1242,11 @@ extern const ssh_kex ssh_ec_kex_nistp521;
 extern const ssh_kexes ssh_ecdh_kex;
 extern const ssh_kexes ssh_ntru_hybrid_kex;
 extern const pq_kemalg ssh_ntru;
+extern const ssh_kexes ssh_mlkem_curve25519_hybrid_kex;
+extern const ssh_kexes ssh_mlkem_nist_hybrid_kex;
+extern const pq_kemalg ssh_mlkem512;
+extern const pq_kemalg ssh_mlkem768;
+extern const pq_kemalg ssh_mlkem1024;
 extern const ssh_keyalg ssh_dsa;
 extern const ssh_keyalg ssh_rsa;
 extern const ssh_keyalg ssh_rsa_sha256;
@@ -1282,6 +1287,13 @@ ssh_hash *blake2b_new_general(unsigned hashlen);
 /* Special test function for AES-GCM */
 void aesgcm_set_prefix_lengths(ssh2_mac *mac, size_t skip, size_t aad);
 
+/* Shake128/256 extendable output functions (like a hash except you don't
+ * commit up front to how much data you want to get out of it) */
+ShakeXOF *shake128_xof_from_input(ptrlen data);
+ShakeXOF *shake256_xof_from_input(ptrlen data);
+void shake_xof_read(ShakeXOF *sx, void *output_v, size_t size);
+void shake_xof_free(ShakeXOF *sx);
+
 /*
  * On some systems, you have to detect hardware crypto acceleration by
  * asking the local OS API rather than OS-agnostically asking the CPU

ssh/transport2.c

@@ -615,6 +615,14 @@ static void ssh2_write_kexinit_lists(
             preferred_kex[n_preferred_kex++] =
                 &ssh_ntru_hybrid_kex;
             break;
+          case KEX_MLKEM_25519_HYBRID:
+            preferred_kex[n_preferred_kex++] =
+                &ssh_mlkem_curve25519_hybrid_kex;
+            break;
+          case KEX_MLKEM_NIST_HYBRID:
+            preferred_kex[n_preferred_kex++] =
+                &ssh_mlkem_nist_hybrid_kex;
+            break;
           case KEX_WARN:
             /* Flag for later. Don't bother if it's the last in
              * the list. */

test/testcrypt-enum.h

@@ -160,6 +160,12 @@ BEGIN_ENUM_TYPE(argon2flavour)
     ENUM_VALUE("Argon2id", Argon2id)
 END_ENUM_TYPE(argon2flavour)
 
+BEGIN_ENUM_TYPE(mlkem_params)
+    ENUM_VALUE("mlkem512", &mlkem_params_512)
+    ENUM_VALUE("mlkem768", &mlkem_params_768)
+    ENUM_VALUE("mlkem1024", &mlkem_params_1024)
+END_ENUM_TYPE(mlkem_params)
+
 BEGIN_ENUM_TYPE(fptype)
     ENUM_VALUE("md5", SSH_FPTYPE_MD5)
     ENUM_VALUE("sha256", SSH_FPTYPE_SHA256)

test/testcrypt-func.h

@@ -405,6 +405,36 @@ FUNC_WRAPPED(int16_list, ntru_encrypt, ARG(int16_list, plaintext),
 FUNC_WRAPPED(int16_list, ntru_decrypt, ARG(int16_list, ciphertext),
              ARG(val_ntrukeypair, keypair))
 
+/*
+ * ML-KEM and its subroutines.
+ */
+FUNC(void, mlkem_keygen,
+     ARG(out_val_string_binarysink, ek), ARG(out_val_string_binarysink, dk),
+     ARG(mlkem_params, params))
+FUNC_WRAPPED(void, mlkem_keygen_internal,
+             ARG(out_val_string_binarysink, ek),
+             ARG(out_val_string_binarysink, dk),
+             ARG(mlkem_params, params),
+             ARG(val_string_ptrlen, d), ARG(val_string_ptrlen, z))
+FUNC_WRAPPED(void, mlkem_keygen_rho_sigma,
+             ARG(out_val_string_binarysink, ek),
+             ARG(out_val_string_binarysink, dk),
+             ARG(mlkem_params, params), ARG(val_string_ptrlen, rho),
+             ARG(val_string_ptrlen, sigma), ARG(val_string_ptrlen, z))
+FUNC(boolean, mlkem_encaps,
+     ARG(out_val_string_binarysink, ciphertext),
+     ARG(out_val_string_binarysink, k),
+     ARG(mlkem_params, params),
+     ARG(val_string_ptrlen, ek))
+FUNC_WRAPPED(boolean, mlkem_encaps_internal,
+             ARG(out_val_string_binarysink, ciphertext),
+             ARG(out_val_string_binarysink, k),
+             ARG(mlkem_params, params),
+             ARG(val_string_ptrlen, ek), ARG(val_string_ptrlen, m))
+FUNC(boolean, mlkem_decaps, ARG(out_val_string_binarysink, k),
+     ARG(mlkem_params, params), ARG(val_string_ptrlen, dk),
+     ARG(val_string_ptrlen, ciphertext))
+
 /*
  * RSA key exchange, and also the BinarySource get function
  * get_ssh1_rsa_priv_agent, which is a convenient way to make an

test/testcrypt.c

@@ -36,6 +36,7 @@
 #include "mpint.h"
 #include "crypto/ecc.h"
 #include "crypto/ntru.h"
+#include "crypto/mlkem.h"
 #include "proxy/cproxy.h"
 
 static NORETURN PRINTF_LIKE(1, 2) void fatal_error(const char *p, ...)
@@ -231,6 +232,7 @@ typedef struct mr_result TD_mr_result;
 typedef Argon2Flavour TD_argon2flavour;
 typedef FingerprintType TD_fptype;
 typedef HttpDigestHash TD_httpdigesthash;
+typedef const mlkem_params *TD_mlkem_params;
 
 #define BEGIN_ENUM_TYPE(name)                                           \
     static bool enum_translate_##name(ptrlen valname, TD_##name *out) { \
@@ -444,12 +446,19 @@ static unsigned *get_out_uint(BinarySource *in)
     return uval;
 }
 
-static BinarySink *get_out_val_string_binarysink(BinarySource *in)
+static strbuf **get_out_val_string(BinarySource *in)
 {
     Value *val = value_new(VT_string);
-    val->vu_string = strbuf_new();
+    val->vu_string = NULL;
     add_finaliser(finaliser_return_value, val);
-    return BinarySink_UPCAST(val->vu_string);
+    return &val->vu_string;
+}
+
+static BinarySink *get_out_val_string_binarysink(BinarySource *in)
+{
+    strbuf *sb = strbuf_new();
+    *get_out_val_string(in) = sb;
+    return BinarySink_UPCAST(sb);
 }
 
 static void return_val_string_asciz_const(strbuf *out, const char *s);
@@ -1031,6 +1040,33 @@ int16_list *ntru_decrypt_wrapper(int16_list *ciphertext, NTRUKeyPair *keypair)
     return out;
 }
 
+void mlkem_keygen_internal_wrapper(
+    BinarySink *ek, BinarySink *dk, const mlkem_params *params,
+    ptrlen d, ptrlen z)
+{
+    assert(d.len == 32 && "Invalid d length");
+    assert(z.len == 32 && "Invalid z length");
+    mlkem_keygen_internal(ek, dk, params, d.ptr, z.ptr);
+}
+
+void mlkem_keygen_rho_sigma_wrapper(
+    BinarySink *ek, BinarySink *dk, const mlkem_params *params,
+    ptrlen rho, ptrlen sigma, ptrlen z)
+{
+    assert(rho.len == 32 && "Invalid rho length");
+    assert(sigma.len == 32 && "Invalid sigma length");
+    assert(z.len == 32 && "Invalid z length");
+    mlkem_keygen_rho_sigma(ek, dk, params, rho.ptr, sigma.ptr, z.ptr);
+}
+
+bool mlkem_encaps_internal_wrapper(BinarySink *ciphertext, BinarySink *kout,
+                                   const mlkem_params *params, ptrlen ek,
+                                   ptrlen m)
+{
+    assert(m.len == 32 && "Invalid m length");
+    return mlkem_encaps_internal(ciphertext, kout, params, ek, m.ptr);
+}
+
 strbuf *rsa_ssh1_encrypt_wrapper(ptrlen input, RSAKey *key)
 {
     /* Fold the boolean return value in C into the string return value

test/testcrypt.py

@@ -182,7 +182,7 @@ def make_argword(arg, argtype, fnname, argindex, argname, to_preserve):
     if typename in {
             "hashalg", "macalg", "keyalg", "cipheralg",
             "dh_group", "ecdh_alg", "rsaorder", "primegenpolicy",
-            "argon2flavour", "fptype", "httpdigesthash"}:
+            "argon2flavour", "fptype", "httpdigesthash", "mlkem_params"}:
         arg = coerce_to_bytes(arg)
         if isinstance(arg, bytes) and b" " not in arg:
             dictkey = (typename, arg)

test/testsc.c

@@ -82,6 +82,7 @@
 #include "mpint.h"
 #include "crypto/ecc.h"
 #include "crypto/ntru.h"
+#include "crypto/mlkem.h"
 
 static NORETURN PRINTF_LIKE(1, 2) void fatal_error(const char *p, ...)
 {
@@ -431,6 +432,9 @@ VOLATILE_WRAPPED_DEFN(static, size_t, looplimit, (size_t x))
     X(argon2)                                   \
     X(primegen_probabilistic)                   \
     X(ntru)                                     \
+    X(mlkem512)                                 \
+    X(mlkem768)                                 \
+    X(mlkem1024)                                \
     X(rfc6979_setup)                            \
     X(rfc6979_attempt)                          \
     /* end of list */
@@ -1745,6 +1749,60 @@ static void test_ntru(void)
     strbuf_free(buffer);
 }
 
+static void test_mlkem(const mlkem_params *params)
+{
+    char rho[32], sigma[32], z[32], m[32], ek[1568], dk[3168], c[1568];
+    char k[32], k2[32];
+
+    /* rho is a random but public value, so side channels are allowed
+     * to reveal it (and undoubtedly will). So we don't vary it
+     * between runs. */
+    random_read(rho, 32);
+
+    for (size_t i = 0; i < looplimit(32); i++) {
+        random_advance_counter();
+        random_read(sigma, 32);
+        random_read(z, 32);
+        random_read(m, 32);
+
+        log_start();
+
+        /* Every other iteration, tamper with the ciphertext so that
+         * implicit rejection occurs, because we need to test that
+         * that too is done in constant time. */
+        unsigned tampering = i & 1;
+
+        buffer_sink ek_sink[1]; buffer_sink_init(ek_sink, ek, sizeof(ek));
+        buffer_sink dk_sink[1]; buffer_sink_init(dk_sink, dk, sizeof(dk));
+        buffer_sink c_sink[1]; buffer_sink_init(c_sink, c, sizeof(c));
+        buffer_sink k_sink[1]; buffer_sink_init(k_sink, k, sizeof(k));
+        mlkem_keygen_rho_sigma(
+            BinarySink_UPCAST(ek_sink), BinarySink_UPCAST(dk_sink),
+            params, rho, sigma, z);
+        ptrlen ek_pl = make_ptrlen(ek, ek_sink->out - ek);
+        ptrlen dk_pl = make_ptrlen(dk, dk_sink->out - dk);
+        mlkem_encaps_internal(
+            BinarySink_UPCAST(c_sink), BinarySink_UPCAST(k_sink),
+            params, ek_pl, m);
+        dk[0] ^= tampering;
+        ptrlen c_pl = make_ptrlen(c, c_sink->out - c);
+        buffer_sink_init(k_sink, k2, sizeof(k2));
+        bool success = mlkem_decaps(
+            BinarySink_UPCAST(k_sink), params, dk_pl, c_pl);
+
+        log_end();
+
+        assert(success);
+        unsigned eq_expected = tampering ^ 1;
+        unsigned eq = smemeq(k, k2, 32);
+        assert(eq == eq_expected);
+    }
+}
+
+static void test_mlkem512(void) { test_mlkem(&mlkem_params_512); }
+static void test_mlkem768(void) { test_mlkem(&mlkem_params_768); }
+static void test_mlkem1024(void) { test_mlkem(&mlkem_params_1024); }
+
 static void test_rfc6979_setup(void)
 {
     mp_int *q = mp_new(512);