mirror of
https://git.tartarus.org/simon/putty.git
synced 2025-01-09 17:38:00 +00:00
e98615f0ba
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.
90 lines
3.5 KiB
C
90 lines
3.5 KiB
C
/*
|
|
* 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 */
|