1 /* Copyright (c) 2024, Google Inc. 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 // MLKEM768_PRIVATE_KEY_BYTES is the length of the data produced by 125 // |MLKEM768_marshal_private_key|. 126 #define MLKEM768_PRIVATE_KEY_BYTES 2400 127 128 // MLKEM768_parse_private_key parses a private key, in NIST's format for 129 // private keys, from |in| and writes the result to |out_private_key|. It 130 // returns one on success or zero on parse error or if there are trailing bytes 131 // in |in|. This format is verbose and should be avoided. Private keys should be 132 // stored as seeds and parsed using |MLKEM768_private_key_from_seed|. 133 OPENSSL_EXPORT int MLKEM768_parse_private_key( 134 struct MLKEM768_private_key *out_private_key, CBS *in); 135 136 137 // ML-KEM-1024 138 // 139 // ML-KEM-1024 also exists. You should prefer ML-KEM-768 where possible. 140 141 // MLKEM1024_public_key contains an ML-KEM-1024 public key. The contents of this 142 // object should never leave the address space since the format is unstable. 143 struct MLKEM1024_public_key { 144 union { 145 uint8_t bytes[512 * (4 + 16) + 32 + 32]; 146 uint16_t alignment; 147 } opaque; 148 }; 149 150 // MLKEM1024_private_key contains a ML-KEM-1024 private key. The contents of 151 // this object should never leave the address space since the format is 152 // unstable. 153 struct MLKEM1024_private_key { 154 union { 155 uint8_t bytes[512 * (4 + 4 + 16) + 32 + 32 + 32]; 156 uint16_t alignment; 157 } opaque; 158 }; 159 160 // MLKEM1024_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-KEM-1024 161 // public key. 162 #define MLKEM1024_PUBLIC_KEY_BYTES 1568 163 164 // MLKEM1024_generate_key generates a random public/private key pair, writes the 165 // encoded public key to |out_encoded_public_key| and sets |out_private_key| to 166 // the private key. If |optional_out_seed| is not NULL then the seed used to 167 // generate the private key is written to it. 168 OPENSSL_EXPORT void MLKEM1024_generate_key( 169 uint8_t out_encoded_public_key[MLKEM1024_PUBLIC_KEY_BYTES], 170 uint8_t optional_out_seed[MLKEM_SEED_BYTES], 171 struct MLKEM1024_private_key *out_private_key); 172 173 // MLKEM1024_private_key_from_seed derives a private key from a seed that was 174 // generated by |MLKEM1024_generate_key|. It fails and returns 0 if |seed_len| 175 // is incorrect, otherwise it writes |*out_private_key| and returns 1. 176 OPENSSL_EXPORT int MLKEM1024_private_key_from_seed( 177 struct MLKEM1024_private_key *out_private_key, const uint8_t *seed, 178 size_t seed_len); 179 180 // MLKEM1024_public_from_private sets |*out_public_key| to the public key that 181 // corresponds to |private_key|. (This is faster than parsing the output of 182 // |MLKEM1024_generate_key| if, for some reason, you need to encapsulate to a 183 // key that was just generated.) 184 OPENSSL_EXPORT void MLKEM1024_public_from_private( 185 struct MLKEM1024_public_key *out_public_key, 186 const struct MLKEM1024_private_key *private_key); 187 188 // MLKEM1024_CIPHERTEXT_BYTES is number of bytes in the ML-KEM-1024 ciphertext. 189 #define MLKEM1024_CIPHERTEXT_BYTES 1568 190 191 // MLKEM1024_encap encrypts a random shared secret for |public_key|, writes the 192 // ciphertext to |out_ciphertext|, and writes the random shared secret to 193 // |out_shared_secret|. 194 OPENSSL_EXPORT void MLKEM1024_encap( 195 uint8_t out_ciphertext[MLKEM1024_CIPHERTEXT_BYTES], 196 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 197 const struct MLKEM1024_public_key *public_key); 198 199 // MLKEM1024_decap decrypts a shared secret from |ciphertext| using 200 // |private_key| and writes it to |out_shared_secret|. If |ciphertext_len| is 201 // incorrect it returns 0, otherwise it returns 1. If |ciphertext| is invalid 202 // (but of the correct length), |out_shared_secret| is filled with a key that 203 // will always be the same for the same |ciphertext| and |private_key|, but 204 // which appears to be random unless one has access to |private_key|. These 205 // alternatives occur in constant time. Any subsequent symmetric encryption 206 // using |out_shared_secret| must use an authenticated encryption scheme in 207 // order to discover the decapsulation failure. 208 OPENSSL_EXPORT int MLKEM1024_decap( 209 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 210 const uint8_t *ciphertext, size_t ciphertext_len, 211 const struct MLKEM1024_private_key *private_key); 212 213 214 // Serialisation of ML-KEM-1024 keys. 215 216 // MLKEM1024_marshal_public_key serializes |public_key| to |out| in the standard 217 // format for ML-KEM-1024 public keys. It returns one on success or zero on 218 // allocation error. 219 OPENSSL_EXPORT int MLKEM1024_marshal_public_key( 220 CBB *out, const struct MLKEM1024_public_key *public_key); 221 222 // MLKEM1024_parse_public_key parses a public key, in the format generated by 223 // |MLKEM1024_marshal_public_key|, from |in| and writes the result to 224 // |out_public_key|. It returns one on success or zero on parse error or if 225 // there are trailing bytes in |in|. 226 OPENSSL_EXPORT int MLKEM1024_parse_public_key( 227 struct MLKEM1024_public_key *out_public_key, CBS *in); 228 229 // MLKEM1024_PRIVATE_KEY_BYTES is the length of the data produced by 230 // |MLKEM1024_marshal_private_key|. 231 #define MLKEM1024_PRIVATE_KEY_BYTES 3168 232 233 // MLKEM1024_parse_private_key parses a private key, in NIST's format for 234 // private keys, from |in| and writes the result to |out_private_key|. It 235 // returns one on success or zero on parse error or if there are trailing bytes 236 // in |in|. This format is verbose and should be avoided. Private keys should be 237 // stored as seeds and parsed using |MLKEM1024_private_key_from_seed|. 238 OPENSSL_EXPORT int MLKEM1024_parse_private_key( 239 struct MLKEM1024_private_key *out_private_key, CBS *in); 240 241 242 #if defined(__cplusplus) 243 } // extern C 244 #endif 245 246 #endif // OPENSSL_HEADER_MLKEM_H 247