1 files changed, 139 insertions, 190 deletions

diff --git a/src/lib/libcrypto/mlkem/mlkem.h b/src/lib/libcrypto/mlkem/mlkem.h
index a2c5d7fed0..31d4858195 100644
--- a/src/lib/libcrypto/mlkem/mlkem.h
+++ b/src/lib/libcrypto/mlkem/mlkem.h
@@ -1,6 +1,6 @@
-/*      $OpenBSD: mlkem.h,v 1.6 2025/05/19 06:47:40 beck Exp $ */
+/*      $OpenBSD: mlkem.h,v 1.7 2025/08/14 15:48:48 beck Exp $ */
 /*
- * Copyright (c) 2024, Google Inc.
+ * Copyright (c) 2025 Bob Beck <beck@obtuse.com>
  *
  * Permission to use, copy, modify, and/or distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -26,253 +26,202 @@ extern "C" {
 #endif
 
 /*
- * ML-KEM-768
- *
- * This implements the Module-Lattice-Based Key-Encapsulation Mechanism from
- * https://csrc.nist.gov/pubs/fips/204/final
+ * ML-KEM constants
  */
 
-/*
- * MLKEM768_public_key contains a ML-KEM-768 public key. The contents of this
- * object should never leave the address space since the format is unstable.
- */
-struct MLKEM768_public_key {
-        union {
-                uint8_t bytes[512 * (3 + 9) + 32 + 32];
-                uint16_t alignment;
-        } opaque;
-};
-
-/*
- * MLKEM768_private_key contains a ML-KEM-768 private key. The contents of this
- * object should never leave the address space since the format is unstable.
- */
-struct MLKEM768_private_key {
-        union {
-                uint8_t bytes[512 * (3 + 3 + 9) + 32 + 32 + 32];
-                uint16_t alignment;
-        } opaque;
-};
+#define RANK768 3
+#define RANK1024 4
 
 /*
- * MLKEM768_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-KEM768 public
- * key.
+ * ML-KEM keys
  */
-#define MLKEM768_PUBLIC_KEY_BYTES 1184
 
-/* MLKEM_SEED_BYTES is the number of bytes in an ML-KEM seed. */
-#define MLKEM_SEED_BYTES 64
+typedef struct MLKEM_private_key_st MLKEM_private_key;
+typedef struct MLKEM_public_key_st MLKEM_public_key;
 
 /*
- *  MLKEM_SHARED_SECRET_BYTES is the number of bytes in the ML-KEM768 shared
- * secret. Although the round-3 specification has a variable-length output, the
- * final ML-KEM construction is expected to use a fixed 32-byte output. To
- * simplify the future transition, we apply the same restriction.
+ * MLKEM_private_key_new allocates a new uninitialized ML-KEM private key for
+ * |rank|, which must be RANK768 or RANK1024. It returns a pointer to an
+ * allocated structure suitable for holding a generated private key of the
+ * corresponding rank on success, NULL is returned on failure. The caller is
+ * responsible for deallocating the resulting key with |MLKEM_private_key_free|.
  */
-#define MLKEM_SHARED_SECRET_BYTES 32
+MLKEM_private_key *MLKEM_private_key_new(int rank);
 
 /*
- * MLKEM_generate_key generates a random public/private key pair, writes the
- * encoded public key to |out_encoded_public_key| and sets |out_private_key| to
- * the private key. If |optional_out_seed| is not NULL then the seed used to
- * generate the private key is written to it.
+ * MLKEM_private_key_free zeroes and frees all memory for |key| if |key| is
+ * non NULL. If |key| is NULL it does nothing and returns.
  */
-int MLKEM768_generate_key(
-    uint8_t out_encoded_public_key[MLKEM768_PUBLIC_KEY_BYTES],
-    uint8_t optional_out_seed[MLKEM_SEED_BYTES],
-    struct MLKEM768_private_key *out_private_key);
+void MLKEM_private_key_free(MLKEM_private_key *key);
 
 /*
- * MLKEM768_private_key_from_seed derives a private key from a seed that was
- * generated by |MLKEM768_generate_key|. It fails and returns 0 if |seed_len| is
- * incorrect, otherwise it writes |*out_private_key| and returns 1.
+ * MLKEM_private_key_encoded_length the number of bytes used by the encoded form
+ * of |key|. Thie corresponds to the length of the buffer allocated for the
+ * encoded_public_key from |MLKEM_marshal_private_key|. Zero is returned if
+ * |key| is NULL or has an invalid rank.
  */
-int MLKEM768_private_key_from_seed(struct MLKEM768_private_key *out_private_key,
-    const uint8_t *seed, size_t seed_len);
+size_t MLKEM_private_key_encoded_length(const MLKEM_private_key *key);
 
 /*
- * MLKEM_public_from_private sets |*out_public_key| to the public key that
- * corresponds to |private_key|. (This is faster than parsing the output of
- * |MLKEM_generate_key| if, for some reason, you need to encapsulate to a key
- * that was just generated.)
+ * MLKEM_private_key_ciphertext_length returns the number of bytes of ciphertext
+ * required to decrypt a shared secret with |key| using |MLKEM_decap|. Zero is
+ * returned if |key| is NULL or has an invalid rank.
  */
-void MLKEM768_public_from_private(struct MLKEM768_public_key *out_public_key,
-    const struct MLKEM768_private_key *private_key);
-
-/* MLKEM768_CIPHERTEXT_BYTES is number of bytes in the ML-KEM768 ciphertext. */
-#define MLKEM768_CIPHERTEXT_BYTES 1088
+size_t MLKEM_private_key_ciphertext_length(const MLKEM_private_key *key);
 
 /*
- * MLKEM768_encap encrypts a random shared secret for |public_key|, writes the
- * ciphertext to |out_ciphertext|, and writes the random shared secret to
- * |out_shared_secret|.
+ * MLKEM_public_key_new allocates a new uninitialized ML-KEM public key for
+ * |rank|, which must be RANK768 or RANK1024. It returns a pointer to an
+ * allocated structure suitable for holding a generated public key of the
+ * corresponding rank on success, NULL is returned on failure. The caller is
+ * responsible for deallocating the resulting key with |MLKEM_public_key_free|.
  */
-void MLKEM768_encap(uint8_t out_ciphertext[MLKEM768_CIPHERTEXT_BYTES],
-    uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES],
-    const struct MLKEM768_public_key *public_key);
+MLKEM_public_key *MLKEM_public_key_new(int rank);
 
 /*
- * MLKEM768_decap decrypts a shared secret from |ciphertext| using |private_key|
- * and writes it to |out_shared_secret|. If |ciphertext_len| is incorrect it
- * returns 0, otherwise it rreturns 1. If |ciphertext| is invalid,
- * |out_shared_secret| is filled with a key that will always be the same for the
- * same |ciphertext| and |private_key|, but which appears to be random unless
- * one has access to |private_key|. These alternatives occur in constant time.
- * Any subsequent symmetric encryption using |out_shared_secret| must use an
- * authenticated encryption scheme in order to discover the decapsulation
- * failure.
+ * MLKEM_public_key_free zeros and deallocates all memory for |key| if |key| is
+ * non NULL. If |key| is NULL it does nothing and returns.
  */
-int MLKEM768_decap(uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES],
-    const uint8_t *ciphertext, size_t ciphertext_len,
-    const struct MLKEM768_private_key *private_key);
-
-/* Serialisation of keys. */
+void MLKEM_public_key_free(MLKEM_public_key *key);
 
 /*
- * MLKEM768_marshal_public_key serializes |public_key| to |out| in the standard
- * format for ML-KEM public keys. It returns one on success or zero on allocation
- * error.
+ * MLKEM_public_key_encoded_length the number of bytes used by the encoded form
+ * of |key|. Thie corresponds to the length of the buffer allocated for the
+ * encoded_public_key from |MLKEM_generate_key| or |MLKEM_marshal_public_key|.
+ * Zero is returned if |key| is NULL or has an invalid rank.
  */
-int MLKEM768_marshal_public_key(uint8_t **output, size_t *output_len,
-    const struct MLKEM768_public_key *public_key);
+size_t MLKEM_public_key_encoded_length(const MLKEM_public_key *key);
 
 /*
- * MLKEM768_parse_public_key parses a public key, in the format generated by
- * |MLKEM_marshal_public_key|, from |in| and writes the result to
- * |out_public_key|. It returns one on success or zero on parse error or if
- * there are trailing bytes in |in|.
+ * MLKEM_public_key_cipertext_length returns the number of bytes produced as the
+ * ciphertext when encrypting a shared secret with |key| using |MLKEM_encap|. Zero
+ * is returned if |key| is NULL or has an invalid rank.
  */
-int MLKEM768_parse_public_key(struct MLKEM768_public_key *out_public_key,
-    const uint8_t *input, size_t input_len);
+size_t MLKEM_public_key_ciphertext_length(const MLKEM_public_key *key);
 
 /*
- * MLKEM_parse_private_key parses a private key, in the format generated by
- * |MLKEM_marshal_private_key|, from |in| and writes the result to
- * |out_private_key|. It returns one on success or zero on parse error or if
- * there are trailing bytes in |in|. This formate is verbose and should be avoided.
- * Private keys should be stored as seeds and parsed using |MLKEM768_private_key_from_seed|.
+ * ML-KEM operations
  */
-int MLKEM768_parse_private_key(struct MLKEM768_private_key *out_private_key,
-    const uint8_t *input, size_t input_len);
 
 /*
- * ML-KEM-1024
+ * MLKEM_generate_key generates a random private/public key pair, initializing
+ * |private_key|. It returns one on success, and zero on failure or error.
+ * |private_key| must be a new uninitialized key. |*out_encoded_public_key| and
+ * |*out_optional_seed|, if provided, must have the value of NULL. On success, a
+ * pointer to the encoded public key of the correct size for |key| is returned
+ * in |out_encoded_public_key|, and the length in bytes of
+ * |*out_encoded_public_key| is returned in |out_encoded_public_key_len|. If
+ * |out_optional_seed| is not NULL, a pointer to the seed used to generate the
+ * private key is returned in |*out_optional_seed| and the length in bytes of
+ * the seed is returned in |*out_optional_seed_len|. The caller is responsible
+ * for freeing the values returned in |out_encoded_public_key|, and
+ * |out_optional_seed|.
  *
- * ML-KEM-1024 also exists. You should prefer ML-KEM-768 where possible.
- */
-
-/*
- * MLKEM1024_public_key contains an ML-KEM-1024 public key. The contents of this
- * object should never leave the address space since the format is unstable.
- */
-struct MLKEM1024_public_key {
-        union {
-                uint8_t bytes[512 * (4 + 16) + 32 + 32];
-                uint16_t alignment;
-        } opaque;
-};
-
-/*
- * MLKEM1024_private_key contains a ML-KEM-1024 private key. The contents of
- * this object should never leave the address space since the format is
- * unstable.
- */
-struct MLKEM1024_private_key {
-        union {
-                uint8_t bytes[512 * (4 + 4 + 16) + 32 + 32 + 32];
-                uint16_t alignment;
-        } opaque;
-};
-
-/*
- * MLKEM1024_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-KEM-1024
- * public key.
+ * In the event a private key needs to be saved, The normal best practice is to
+ * save |out_optional_seed| as the private key, along with the ML-KEM rank value.
+ * An MLKEM_private_key of the correct rank can then be constructed using
+ * |MLKEM_private_key_from_seed|.
  */
-#define MLKEM1024_PUBLIC_KEY_BYTES 1568
+int MLKEM_generate_key(MLKEM_private_key *private_key,
+    uint8_t **out_encoded_public_key, size_t *out_encoded_public_key_len,
+    uint8_t **out_optional_seed, size_t *out_optional_seed_len);
 
 /*
- * MLKEM1024_generate_key generates a random public/private key pair, writes the
- * encoded public key to |out_encoded_public_key| and sets |out_private_key| to
- * the private key. If |optional_out_seed| is not NULL then the seed used to
- * generate the private key is written to it.
+ * MLKEM_private_key_from_seed derives a private key from a seed that was
+ * generated by |MLKEM_generate_key| initializing |private_key|. It returns one
+ * on success, and zero on failure or error. |private_key| must be a new
+ * uninitialized key. |seed_len| must be MLKEM_SEED_LENGTH.
+ *
+ * For |private_key| to match the key generated by |MLKEM_generate_key|,
+ * |private_key| must have been created with the same rank as used when generating
+ * the key.
  */
-int MLKEM1024_generate_key(
-    uint8_t out_encoded_public_key[MLKEM1024_PUBLIC_KEY_BYTES],
-    uint8_t optional_out_seed[MLKEM_SEED_BYTES],
-    struct MLKEM1024_private_key *out_private_key);
+int MLKEM_private_key_from_seed(MLKEM_private_key *private_key,
+    const uint8_t *seed, size_t seed_len);
 
 /*
- * MLKEM1024_private_key_from_seed derives a private key from a seed that was
- * generated by |MLKEM1024_generate_key|. It fails and returns 0 if |seed_len|
- * is incorrect, otherwise it writes |*out_private_key| and returns 1.
+ * MLKEM_public_from_private initializes |public_key| with the public key that
+ * corresponds to |private_key|. It returns one on success and zero on
+ * error. This is faster than parsing the output of |MLKEM_generate_key| if, for
+ * some reason, you need to encapsulate to a key that was just
+ * generated. |private key| must be a new uninitialized key, of the same rank as
+ * |public_key|.
  */
-int MLKEM1024_private_key_from_seed(
-    struct MLKEM1024_private_key *out_private_key, const uint8_t *seed,
-    size_t seed_len);
+int MLKEM_public_from_private(const MLKEM_private_key *private_key,
+    MLKEM_public_key *public_key);
 
 /*
- * MLKEM1024_public_from_private sets |*out_public_key| to the public key that
- * corresponds to |private_key|. (This is faster than parsing the output of
- * |MLKEM1024_generate_key| if, for some reason, you need to encapsulate to a
- * key that was just generated.)
+ * MLKEM_encap encrypts a random shared secret for an initialized
+ * |public_key|. It returns one on success, and zero on failure or error. |*out
+ * ciphertext| and |*out_shared_secret| must have the value NULL. On success, a
+ * pointer to the ciphertext of the correct size for |key| is returned in
+ * |out_ciphertext|, the length in bytes of |*out_ciphertext| is returned in
+ * |*out_ciphertext_len|, a pointer to the random shared secret is returned in
+ * |out_shared_secret|, and the length in bytes of |*out_shared_secret| is
+ * returned in |*out_ciphtertext_len|. The caller is responsible for zeroing and
+ * freeing the values returned in |out_ciphertext| and |out_shared_secret|
  */
-void MLKEM1024_public_from_private(struct MLKEM1024_public_key *out_public_key,
-    const struct MLKEM1024_private_key *private_key);
-
-/* MLKEM1024_CIPHERTEXT_BYTES is number of bytes in the ML-KEM-1024 ciphertext. */
-#define MLKEM1024_CIPHERTEXT_BYTES 1568
+int MLKEM_encap(const MLKEM_public_key *public_key,
+    uint8_t **out_ciphertext, size_t *out_ciphertext_len,
+    uint8_t **out_shared_secret, size_t *out_shared_secret_len);
 
 /*
- * MLKEM1024_encap encrypts a random shared secret for |public_key|, writes the
- * ciphertext to |out_ciphertext|, and writes the random shared secret to
- * |out_shared_secret|.
- */
-void MLKEM1024_encap(uint8_t out_ciphertext[MLKEM1024_CIPHERTEXT_BYTES],
-    uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES],
-    const struct MLKEM1024_public_key *public_key);
-
-/*
- * MLKEM1024_decap decrypts a shared secret from |ciphertext| using
- * |private_key| and writes it to |out_shared_secret|. If |ciphertext_len| is
- * incorrect it returns 0, otherwise it returns 1. If |ciphertext| is invalid
- * (but of the correct length), |out_shared_secret| is filled with a key that
- * will always be the same for the same |ciphertext| and |private_key|, but
- * which appears to be random unless one has access to |private_key|. These
- * alternatives occur in constant time. Any subsequent symmetric encryption
- * using |out_shared_secret| must use an authenticated encryption scheme in
- * order to discover the decapsulation failure.
+ * MLKEM_decap decrypts a shared secret from |ciphertext| using an initialized
+ * |private_key|. It returns a pointer to the shared secret|out_shared_secret|
+ * and the length in bytes of |*out_shared_secret| in |*out_shared_secret_len|.
+ *
+ * If |ciphertext_len| is incorrect for |private_key|, |*out_shared_secret| is
+ * not NULL, or memory can not be allocated, it returns zero, otherwise it
+ * returns one. If |ciphertext| is invalid, a pointer is returned in
+ * |out_shared_secret| pointing to a key that will always be the same for the
+ * same |ciphertext| and |private_key|, but which appears to be random unless
+ * one has access to |private_key|. These alternatives occur in constant time.
+ * Any subsequent symmetric encryption using |out_shared_secret| must use an
+ * authenticated encryption scheme in order to discover the decapsulation
+ * failure. The caller is responsible for zeroing and freeing the value returned
+ * in |out_shared_secret|.
  */
-int MLKEM1024_decap(uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES],
+int MLKEM_decap(const MLKEM_private_key *private_key,
     const uint8_t *ciphertext, size_t ciphertext_len,
-    const struct MLKEM1024_private_key *private_key);
+    uint8_t **out_shared_secret, size_t *out_shared_secret_len);
+
+/* Serialization of ML-KEM keys. */
 
 /*
- * Serialisation of ML-KEM-1024 keys.
- * MLKEM1024_marshal_public_key serializes |public_key| to |out| in the standard
- * format for ML-KEM-1024 public keys. It returns one on success or zero on
- * allocation error.
+ * MLKEM_marshal_public_key serializes an initialized |public_key| in the
+ * standard format for ML-KEM public keys. It returns one on success or zero on
+ * allocation error or failure. |*out| must have the value NULL. On success a
+ * pointer is returned in |out| to the encoded public key matching |public_key|,
+ * and a pointer to the length in bytes of the encoded public key is stored in
+ * |out_len|. The caller is responsible for freeing the values returned in
+ * |out|.
  */
-int MLKEM1024_marshal_public_key(uint8_t **output, size_t *output_len,
-    const struct MLKEM1024_public_key *public_key);
+int MLKEM_marshal_public_key(const MLKEM_public_key *public_key, uint8_t **out,
+    size_t *out_len);
 
 /*
- * MLKEM1024_parse_public_key parses a public key, in the format generated by
- * |MLKEM1024_marshal_public_key|, from |in| and writes the result to
- * |out_public_key|. It returns one on success or zero on parse error or if
- * there are trailing bytes in |in|.
+ * MLKEM_parse_public_key parses a public key, in the format generated by
+ * |MLKEM_marshal_public_key|, from |in|. It returns one on success or zero on
+ * error or failure. |public_key| must be a new uninitialized key. |in_len| must
+ * be the correct length for the encoded format of |public_key. On success
+ * |public_key| is initialized to the value parsed from |in|.
  */
-int MLKEM1024_parse_public_key(struct MLKEM1024_public_key *out_public_key,
-    const uint8_t *input, size_t input_len);
+int MLKEM_parse_public_key(MLKEM_public_key *public_key, const uint8_t *in,
+    size_t in_len);
 
 /*
- * MLKEM1024_parse_private_key parses a private key, in NIST's format for
- * private keys, from |in| and writes the result to |out_private_key|. It
- * returns one on success or zero on parse error or if there are trailing bytes
- * in |in|. This format is verbose and should be avoided. Private keys should be
- * stored as seeds and parsed using |MLKEM1024_private_key_from_seed|.
+ * MLKEM_parse_private_key parses a private key, in the format generated by
+ * |MLKEM_marshal_private_key|, from |in|. It returns one on success or zero on
+ * error or failure. |private_key| must be a new uninitialized key. |in_len|
+ * must be the correct length for the encoded format of |private_key. On success
+ * |private_key| is initialized to the value parsed from |in|.
+ *
+ * This format is wastefully verbose and should be avoided. Private keys should
+ * be stored as seeds from |MLKEM_generate_key|, and then parsed using
+ * |MLKEM_private_key_from_seed|.
  */
-int MLKEM1024_parse_private_key(struct MLKEM1024_private_key *out_private_key,
-    const uint8_t *input, size_t input_len);
+int MLKEM_parse_private_key(MLKEM_private_key *private_key, const uint8_t *in,
+    size_t in_len);
 
 #if defined(__cplusplus)
 }