1 /* Copyright 2024 The BoringSSL Authors 2 * 3 * Permission to use, copy, modify, and/or distribute this software for any 4 * purpose with or without fee is hereby granted, provided that the above 5 * copyright notice and this permission notice appear in all copies. 6 * 7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ 14 15 #ifndef OPENSSL_HEADER_MLKEM_H 16 #define OPENSSL_HEADER_MLKEM_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // ML-KEM-768. 26 // 27 // This implements the Module-Lattice-Based Key-Encapsulation Mechanism from 28 // https://csrc.nist.gov/pubs/fips/204/final 29 30 31 // MLKEM768_public_key contains an ML-KEM-768 public key. The contents of this 32 // object should never leave the address space since the format is unstable. 33 struct MLKEM768_public_key { 34 union { 35 uint8_t bytes[512 * (3 + 9) + 32 + 32]; 36 uint16_t alignment; 37 } opaque; 38 }; 39 40 // MLKEM768_private_key contains an ML-KEM-768 private key. The contents of this 41 // object should never leave the address space since the format is unstable. 42 struct MLKEM768_private_key { 43 union { 44 uint8_t bytes[512 * (3 + 3 + 9) + 32 + 32 + 32]; 45 uint16_t alignment; 46 } opaque; 47 }; 48 49 // MLKEM768_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-KEM-768 50 // public key. 51 #define MLKEM768_PUBLIC_KEY_BYTES 1184 52 53 // MLKEM_SEED_BYTES is the number of bytes in an ML-KEM seed. 54 #define MLKEM_SEED_BYTES 64 55 56 // MLKEM768_generate_key generates a random public/private key pair, writes the 57 // encoded public key to |out_encoded_public_key| and sets |out_private_key| to 58 // the private key. If |optional_out_seed| is not NULL then the seed used to 59 // generate the private key is written to it. 60 OPENSSL_EXPORT void MLKEM768_generate_key( 61 uint8_t out_encoded_public_key[MLKEM768_PUBLIC_KEY_BYTES], 62 uint8_t optional_out_seed[MLKEM_SEED_BYTES], 63 struct MLKEM768_private_key *out_private_key); 64 65 // MLKEM768_private_key_from_seed derives a private key from a seed that was 66 // generated by |MLKEM768_generate_key|. It fails and returns 0 if |seed_len| is 67 // incorrect, otherwise it writes |*out_private_key| and returns 1. 68 OPENSSL_EXPORT int MLKEM768_private_key_from_seed( 69 struct MLKEM768_private_key *out_private_key, const uint8_t *seed, 70 size_t seed_len); 71 72 // MLKEM768_public_from_private sets |*out_public_key| to the public key that 73 // corresponds to |private_key|. (This is faster than parsing the output of 74 // |MLKEM768_generate_key| if, for some reason, you need to encapsulate to a key 75 // that was just generated.) 76 OPENSSL_EXPORT void MLKEM768_public_from_private( 77 struct MLKEM768_public_key *out_public_key, 78 const struct MLKEM768_private_key *private_key); 79 80 // MLKEM768_CIPHERTEXT_BYTES is number of bytes in the ML-KEM-768 ciphertext. 81 #define MLKEM768_CIPHERTEXT_BYTES 1088 82 83 // MLKEM_SHARED_SECRET_BYTES is the number of bytes in an ML-KEM shared secret. 84 #define MLKEM_SHARED_SECRET_BYTES 32 85 86 // MLKEM768_encap encrypts a random shared secret for |public_key|, writes the 87 // ciphertext to |out_ciphertext|, and writes the random shared secret to 88 // |out_shared_secret|. 89 OPENSSL_EXPORT void MLKEM768_encap( 90 uint8_t out_ciphertext[MLKEM768_CIPHERTEXT_BYTES], 91 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 92 const struct MLKEM768_public_key *public_key); 93 94 // MLKEM768_decap decrypts a shared secret from |ciphertext| using |private_key| 95 // and writes it to |out_shared_secret|. If |ciphertext_len| is incorrect it 96 // returns 0, otherwise it returns 1. If |ciphertext| is invalid (but of the 97 // correct length), |out_shared_secret| is filled with a key that will always be 98 // the same for the same |ciphertext| and |private_key|, but which appears to be 99 // random unless one has access to |private_key|. These alternatives occur in 100 // constant time. Any subsequent symmetric encryption using |out_shared_secret| 101 // must use an authenticated encryption scheme in order to discover the 102 // decapsulation failure. 103 OPENSSL_EXPORT int MLKEM768_decap( 104 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 105 const uint8_t *ciphertext, size_t ciphertext_len, 106 const struct MLKEM768_private_key *private_key); 107 108 109 // Serialisation of keys. 110 111 // MLKEM768_marshal_public_key serializes |public_key| to |out| in the standard 112 // format for ML-KEM-768 public keys. It returns one on success or zero on 113 // allocation error. 114 OPENSSL_EXPORT int MLKEM768_marshal_public_key( 115 CBB *out, const struct MLKEM768_public_key *public_key); 116 117 // MLKEM768_parse_public_key parses a public key, in the format generated by 118 // |MLKEM768_marshal_public_key|, from |in| and writes the result to 119 // |out_public_key|. It returns one on success or zero on parse error or if 120 // there are trailing bytes in |in|. 121 OPENSSL_EXPORT int MLKEM768_parse_public_key( 122 struct MLKEM768_public_key *out_public_key, CBS *in); 123 124 125 // ML-KEM-1024 126 // 127 // ML-KEM-1024 also exists. You should prefer ML-KEM-768 where possible. 128 129 // MLKEM1024_public_key contains an ML-KEM-1024 public key. The contents of this 130 // object should never leave the address space since the format is unstable. 131 struct MLKEM1024_public_key { 132 union { 133 uint8_t bytes[512 * (4 + 16) + 32 + 32]; 134 uint16_t alignment; 135 } opaque; 136 }; 137 138 // MLKEM1024_private_key contains a ML-KEM-1024 private key. The contents of 139 // this object should never leave the address space since the format is 140 // unstable. 141 struct MLKEM1024_private_key { 142 union { 143 uint8_t bytes[512 * (4 + 4 + 16) + 32 + 32 + 32]; 144 uint16_t alignment; 145 } opaque; 146 }; 147 148 // MLKEM1024_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-KEM-1024 149 // public key. 150 #define MLKEM1024_PUBLIC_KEY_BYTES 1568 151 152 // MLKEM1024_generate_key generates a random public/private key pair, writes the 153 // encoded public key to |out_encoded_public_key| and sets |out_private_key| to 154 // the private key. If |optional_out_seed| is not NULL then the seed used to 155 // generate the private key is written to it. 156 OPENSSL_EXPORT void MLKEM1024_generate_key( 157 uint8_t out_encoded_public_key[MLKEM1024_PUBLIC_KEY_BYTES], 158 uint8_t optional_out_seed[MLKEM_SEED_BYTES], 159 struct MLKEM1024_private_key *out_private_key); 160 161 // MLKEM1024_private_key_from_seed derives a private key from a seed that was 162 // generated by |MLKEM1024_generate_key|. It fails and returns 0 if |seed_len| 163 // is incorrect, otherwise it writes |*out_private_key| and returns 1. 164 OPENSSL_EXPORT int MLKEM1024_private_key_from_seed( 165 struct MLKEM1024_private_key *out_private_key, const uint8_t *seed, 166 size_t seed_len); 167 168 // MLKEM1024_public_from_private sets |*out_public_key| to the public key that 169 // corresponds to |private_key|. (This is faster than parsing the output of 170 // |MLKEM1024_generate_key| if, for some reason, you need to encapsulate to a 171 // key that was just generated.) 172 OPENSSL_EXPORT void MLKEM1024_public_from_private( 173 struct MLKEM1024_public_key *out_public_key, 174 const struct MLKEM1024_private_key *private_key); 175 176 // MLKEM1024_CIPHERTEXT_BYTES is number of bytes in the ML-KEM-1024 ciphertext. 177 #define MLKEM1024_CIPHERTEXT_BYTES 1568 178 179 // MLKEM1024_encap encrypts a random shared secret for |public_key|, writes the 180 // ciphertext to |out_ciphertext|, and writes the random shared secret to 181 // |out_shared_secret|. 182 OPENSSL_EXPORT void MLKEM1024_encap( 183 uint8_t out_ciphertext[MLKEM1024_CIPHERTEXT_BYTES], 184 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 185 const struct MLKEM1024_public_key *public_key); 186 187 // MLKEM1024_decap decrypts a shared secret from |ciphertext| using 188 // |private_key| and writes it to |out_shared_secret|. If |ciphertext_len| is 189 // incorrect it returns 0, otherwise it returns 1. If |ciphertext| is invalid 190 // (but of the correct length), |out_shared_secret| is filled with a key that 191 // will always be the same for the same |ciphertext| and |private_key|, but 192 // which appears to be random unless one has access to |private_key|. These 193 // alternatives occur in constant time. Any subsequent symmetric encryption 194 // using |out_shared_secret| must use an authenticated encryption scheme in 195 // order to discover the decapsulation failure. 196 OPENSSL_EXPORT int MLKEM1024_decap( 197 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 198 const uint8_t *ciphertext, size_t ciphertext_len, 199 const struct MLKEM1024_private_key *private_key); 200 201 202 // Serialisation of ML-KEM-1024 keys. 203 204 // MLKEM1024_marshal_public_key serializes |public_key| to |out| in the standard 205 // format for ML-KEM-1024 public keys. It returns one on success or zero on 206 // allocation error. 207 OPENSSL_EXPORT int MLKEM1024_marshal_public_key( 208 CBB *out, const struct MLKEM1024_public_key *public_key); 209 210 // MLKEM1024_parse_public_key parses a public key, in the format generated by 211 // |MLKEM1024_marshal_public_key|, from |in| and writes the result to 212 // |out_public_key|. It returns one on success or zero on parse error or if 213 // there are trailing bytes in |in|. 214 OPENSSL_EXPORT int MLKEM1024_parse_public_key( 215 struct MLKEM1024_public_key *out_public_key, CBS *in); 216 217 218 #if defined(__cplusplus) 219 } // extern C 220 #endif 221 222 #endif // OPENSSL_HEADER_MLKEM_H 223