mlkem.h (14229B)
1 /* mlkem.h 2 * 3 * Copyright (C) 2006-2025 wolfSSL Inc. 4 * 5 * This file is part of wolfSSL. 6 * 7 * wolfSSL is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; either version 3 of the License, or 10 * (at your option) any later version. 11 * 12 * wolfSSL is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA 20 */ 21 22 /*! 23 \file wolfssl/wolfcrypt/mlkem.h 24 */ 25 26 #ifndef WOLF_CRYPT_MLKEM_H 27 #define WOLF_CRYPT_MLKEM_H 28 29 #include <wolfssl/wolfcrypt/types.h> 30 #include <wolfssl/wolfcrypt/random.h> 31 32 #ifdef WOLFSSL_HAVE_MLKEM 33 34 /* Number of co-efficients in polynomial. */ 35 #define MLKEM_N 256 36 37 /* Define algorithm type when not excluded. */ 38 #ifndef WOLFSSL_NO_ML_KEM 39 #if !defined(WOLFSSL_NO_ML_KEM_512) 40 #define WOLFSSL_WC_ML_KEM_512 41 #endif 42 #if !defined(WOLFSSL_NO_ML_KEM_768) 43 #define WOLFSSL_WC_ML_KEM_768 44 #endif 45 #if !defined(WOLFSSL_NO_ML_KEM_1024) 46 #define WOLFSSL_WC_ML_KEM_1024 47 #endif 48 49 #if !defined(WOLFSSL_WC_ML_KEM_512) && !defined(WOLFSSL_WC_ML_KEM_768) && \ 50 !defined(WOLFSSL_WC_ML_KEM_1024) 51 #error "No ML-KEM key size chosen." 52 #endif 53 #endif 54 55 #ifdef WOLFSSL_MLKEM_KYBER 56 #ifndef WOLFSSL_NO_KYBER512 57 #define WOLFSSL_KYBER512 58 #define WOLFSSL_WC_ML_KEM_512 59 #endif 60 #ifndef WOLFSSL_NO_KYBER768 61 #define WOLFSSL_KYBER768 62 #define WOLFSSL_WC_ML_KEM_768 63 #endif 64 #ifndef WOLFSSL_NO_KYBER1024 65 #define WOLFSSL_KYBER1024 66 #define WOLFSSL_WC_ML_KEM_1024 67 #endif 68 69 #if !defined(WOLFSSL_KYBER512) && !defined(WOLFSSL_KYBER768) && \ 70 !defined(WOLFSSL_KYBER1024) 71 #error "No Kyber key size chosen." 72 #endif 73 #endif 74 75 /* Size of a polynomial vector based on dimensions. */ 76 #define MLKEM_POLY_VEC_SZ(k) ((k) * WC_ML_KEM_POLY_SIZE) 77 /* Size of a compressed polynomial based on bits per coefficient. */ 78 #define MLKEM_POLY_COMPRESSED_SZ(b) ((b) * (MLKEM_N / 8)) 79 /* Size of a compressed vector polynomial based on dimensions and bits per 80 * coefficient. */ 81 #define MLKEM_POLY_VEC_COMPRESSED_SZ(k, b) ((k) * ((b) * (MLKEM_N / 8))) 82 83 #ifdef WOLFSSL_WC_ML_KEM_512 84 #define WC_ML_KEM_512_K 2 85 /* Size of a polynomial vector. */ 86 #define WC_ML_KEM_512_POLY_VEC_SZ MLKEM_POLY_VEC_SZ(WC_ML_KEM_512_K) 87 /* Size of a compressed polynomial based on bits per coefficient. */ 88 #define WC_ML_KEM_512_POLY_COMPRESSED_SZ MLKEM_POLY_COMPRESSED_SZ(4) 89 /* Size of a compressed vector polynomial based on dimensions and bits per 90 * coefficient. */ 91 #define WC_ML_KEM_512_POLY_VEC_COMPRESSED_SZ \ 92 MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_512_K, 10) 93 94 /* Public key size. */ 95 #define WC_ML_KEM_512_PUBLIC_KEY_SIZE \ 96 (WC_ML_KEM_512_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ) 97 /* Private key size. */ 98 #define WC_ML_KEM_512_PRIVATE_KEY_SIZE \ 99 (WC_ML_KEM_512_POLY_VEC_SZ + WC_ML_KEM_512_PUBLIC_KEY_SIZE + \ 100 2 * WC_ML_KEM_SYM_SZ) 101 /* Cipher text size. */ 102 #define WC_ML_KEM_512_CIPHER_TEXT_SIZE \ 103 (WC_ML_KEM_512_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_512_POLY_COMPRESSED_SZ) 104 #endif 105 106 #ifdef WOLFSSL_WC_ML_KEM_768 107 #define WC_ML_KEM_768_K 3 108 109 /* Size of a polynomial vector. */ 110 #define WC_ML_KEM_768_POLY_VEC_SZ MLKEM_POLY_VEC_SZ(WC_ML_KEM_768_K) 111 /* Size of a compressed polynomial based on bits per coefficient. */ 112 #define WC_ML_KEM_768_POLY_COMPRESSED_SZ MLKEM_POLY_COMPRESSED_SZ(4) 113 /* Size of a compressed vector polynomial based on dimensions and bits per 114 * coefficient. */ 115 #define WC_ML_KEM_768_POLY_VEC_COMPRESSED_SZ \ 116 MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_768_K, 10) 117 118 /* Public key size. */ 119 #define WC_ML_KEM_768_PUBLIC_KEY_SIZE \ 120 (WC_ML_KEM_768_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ) 121 /* Private key size. */ 122 #define WC_ML_KEM_768_PRIVATE_KEY_SIZE \ 123 (WC_ML_KEM_768_POLY_VEC_SZ + WC_ML_KEM_768_PUBLIC_KEY_SIZE + \ 124 2 * WC_ML_KEM_SYM_SZ) 125 /* Cipher text size. */ 126 #define WC_ML_KEM_768_CIPHER_TEXT_SIZE \ 127 (WC_ML_KEM_768_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_768_POLY_COMPRESSED_SZ) 128 #endif 129 130 #ifdef WOLFSSL_WC_ML_KEM_1024 131 #define WC_ML_KEM_1024_K 4 132 133 /* Size of a polynomial vector. */ 134 #define WC_ML_KEM_1024_POLY_VEC_SZ MLKEM_POLY_VEC_SZ(WC_ML_KEM_1024_K) 135 /* Size of a compressed polynomial based on bits per coefficient. */ 136 #define WC_ML_KEM_1024_POLY_COMPRESSED_SZ MLKEM_POLY_COMPRESSED_SZ(5) 137 /* Size of a compressed vector polynomial based on dimensions and bits per 138 * coefficient. */ 139 #define WC_ML_KEM_1024_POLY_VEC_COMPRESSED_SZ \ 140 MLKEM_POLY_VEC_COMPRESSED_SZ(WC_ML_KEM_1024_K, 11) 141 142 /* Public key size. */ 143 #define WC_ML_KEM_1024_PUBLIC_KEY_SIZE \ 144 (WC_ML_KEM_1024_POLY_VEC_SZ + WC_ML_KEM_SYM_SZ) 145 /* Private key size. */ 146 #define WC_ML_KEM_1024_PRIVATE_KEY_SIZE \ 147 (WC_ML_KEM_1024_POLY_VEC_SZ + WC_ML_KEM_1024_PUBLIC_KEY_SIZE + \ 148 2 * WC_ML_KEM_SYM_SZ) 149 /* Cipher text size. */ 150 #define WC_ML_KEM_1024_CIPHER_TEXT_SIZE \ 151 (WC_ML_KEM_1024_POLY_VEC_COMPRESSED_SZ + WC_ML_KEM_1024_POLY_COMPRESSED_SZ) 152 #endif 153 154 #ifndef WC_ML_KEM_MAX_K 155 #ifdef WOLFSSL_WC_ML_KEM_1024 156 #define WC_ML_KEM_MAX_K WC_ML_KEM_1024_K 157 #define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE WC_ML_KEM_1024_PRIVATE_KEY_SIZE 158 #define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE WC_ML_KEM_1024_PUBLIC_KEY_SIZE 159 #define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE WC_ML_KEM_1024_CIPHER_TEXT_SIZE 160 #elif defined(WOLFSSL_WC_ML_KEM_768) 161 #define WC_ML_KEM_MAX_K WC_ML_KEM_768_K 162 #define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE WC_ML_KEM_768_PRIVATE_KEY_SIZE 163 #define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE WC_ML_KEM_768_PUBLIC_KEY_SIZE 164 #define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE WC_ML_KEM_768_CIPHER_TEXT_SIZE 165 #elif defined(WOLFSSL_WC_ML_KEM_512) 166 #define WC_ML_KEM_MAX_K WC_ML_KEM_512_K 167 #define WC_ML_KEM_MAX_PRIVATE_KEY_SIZE WC_ML_KEM_512_PRIVATE_KEY_SIZE 168 #define WC_ML_KEM_MAX_PUBLIC_KEY_SIZE WC_ML_KEM_512_PUBLIC_KEY_SIZE 169 #define WC_ML_KEM_MAX_CIPHER_TEXT_SIZE WC_ML_KEM_512_CIPHER_TEXT_SIZE 170 #endif 171 #endif /* WC_ML_KEM_MAX_K */ 172 173 #define KYBER_N MLKEM_N 174 175 /* Size of a polynomial vector based on dimensions. */ 176 #define KYBER_POLY_VEC_SZ(k) ((k) * KYBER_POLY_SIZE) 177 /* Size of a compressed polynomial based on bits per coefficient. */ 178 #define KYBER_POLY_COMPRESSED_SZ(b) ((b) * (KYBER_N / 8)) 179 /* Size of a compressed vector polynomial based on dimensions and bits per 180 * coefficient. */ 181 #define KYBER_POLY_VEC_COMPRESSED_SZ(k, b) ((k) * ((b) * (KYBER_N / 8))) 182 183 184 /* Kyber-512 parameters */ 185 /* Number of polynomials in a vector and vectors in a matrix. */ 186 #define KYBER512_K 2 187 188 /* Size of a polynomial vector. */ 189 #define KYBER512_POLY_VEC_SZ KYBER_POLY_VEC_SZ(KYBER512_K) 190 /* Size of a compressed polynomial based on bits per coefficient. */ 191 #define KYBER512_POLY_COMPRESSED_SZ KYBER_POLY_COMPRESSED_SZ(4) 192 /* Size of a compressed vector polynomial based on dimensions and bits per 193 * coefficient. */ 194 #define KYBER512_POLY_VEC_COMPRESSED_SZ \ 195 KYBER_POLY_VEC_COMPRESSED_SZ(KYBER512_K, 10) 196 197 /* Public key size. */ 198 #define KYBER512_PUBLIC_KEY_SIZE \ 199 (KYBER512_POLY_VEC_SZ + KYBER_SYM_SZ) 200 /* Private key size. */ 201 #define KYBER512_PRIVATE_KEY_SIZE \ 202 (KYBER512_POLY_VEC_SZ + KYBER512_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ) 203 /* Cipher text size. */ 204 #define KYBER512_CIPHER_TEXT_SIZE \ 205 (KYBER512_POLY_VEC_COMPRESSED_SZ + KYBER512_POLY_COMPRESSED_SZ) 206 207 /* Kyber-768 parameters */ 208 /* Number of polynomials in a vector and vectors in a matrix. */ 209 #define KYBER768_K 3 210 211 /* Size of a polynomial vector. */ 212 #define KYBER768_POLY_VEC_SZ KYBER_POLY_VEC_SZ(KYBER768_K) 213 /* Size of a compressed polynomial based on bits per coefficient. */ 214 #define KYBER768_POLY_COMPRESSED_SZ KYBER_POLY_COMPRESSED_SZ(4) 215 /* Size of a compressed vector polynomial based on dimensions and bits per 216 * coefficient. */ 217 #define KYBER768_POLY_VEC_COMPRESSED_SZ \ 218 KYBER_POLY_VEC_COMPRESSED_SZ(KYBER768_K, 10) 219 220 /* Public key size. */ 221 #define KYBER768_PUBLIC_KEY_SIZE \ 222 (KYBER768_POLY_VEC_SZ + KYBER_SYM_SZ) 223 /* Private key size. */ 224 #define KYBER768_PRIVATE_KEY_SIZE \ 225 (KYBER768_POLY_VEC_SZ + KYBER768_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ) 226 /* Cipher text size. */ 227 #define KYBER768_CIPHER_TEXT_SIZE \ 228 (KYBER768_POLY_VEC_COMPRESSED_SZ + KYBER768_POLY_COMPRESSED_SZ) 229 230 /* Kyber-1024 parameters */ 231 /* Number of polynomials in a vector and vectors in a matrix. */ 232 #define KYBER1024_K 4 233 234 /* Size of a polynomial vector. */ 235 #define KYBER1024_POLY_VEC_SZ KYBER_POLY_VEC_SZ(KYBER1024_K) 236 /* Size of a compressed polynomial based on bits per coefficient. */ 237 #define KYBER1024_POLY_COMPRESSED_SZ KYBER_POLY_COMPRESSED_SZ(5) 238 /* Size of a compressed vector polynomial based on dimensions and bits per 239 * coefficient. */ 240 #define KYBER1024_POLY_VEC_COMPRESSED_SZ \ 241 KYBER_POLY_VEC_COMPRESSED_SZ(KYBER1024_K, 11) 242 243 /* Public key size. */ 244 #define KYBER1024_PUBLIC_KEY_SIZE \ 245 (KYBER1024_POLY_VEC_SZ + KYBER_SYM_SZ) 246 /* Private key size. */ 247 #define KYBER1024_PRIVATE_KEY_SIZE \ 248 (KYBER1024_POLY_VEC_SZ + KYBER1024_PUBLIC_KEY_SIZE + 2 * KYBER_SYM_SZ) 249 /* Cipher text size. */ 250 #define KYBER1024_CIPHER_TEXT_SIZE \ 251 (KYBER1024_POLY_VEC_COMPRESSED_SZ + KYBER1024_POLY_COMPRESSED_SZ) 252 253 254 /* Maximum dimensions and sizes of supported key types. */ 255 #ifdef WOLFSSL_KYBER1024 256 #define KYBER_MAX_K KYBER1024_K 257 #define KYBER_MAX_PRIVATE_KEY_SIZE KYBER1024_PRIVATE_KEY_SIZE 258 #define KYBER_MAX_PUBLIC_KEY_SIZE KYBER1024_PUBLIC_KEY_SIZE 259 #define KYBER_MAX_CIPHER_TEXT_SIZE KYBER1024_CIPHER_TEXT_SIZE 260 #elif defined(WOLFSSL_KYBER768) 261 #define KYBER_MAX_K KYBER768_K 262 #define KYBER_MAX_PRIVATE_KEY_SIZE KYBER768_PRIVATE_KEY_SIZE 263 #define KYBER_MAX_PUBLIC_KEY_SIZE KYBER768_PUBLIC_KEY_SIZE 264 #define KYBER_MAX_CIPHER_TEXT_SIZE KYBER768_CIPHER_TEXT_SIZE 265 #elif defined(WOLFSSL_KYBER512) 266 #define KYBER_MAX_K KYBER512_K 267 #define KYBER_MAX_PRIVATE_KEY_SIZE KYBER512_PRIVATE_KEY_SIZE 268 #define KYBER_MAX_PUBLIC_KEY_SIZE KYBER512_PUBLIC_KEY_SIZE 269 #define KYBER_MAX_CIPHER_TEXT_SIZE KYBER512_CIPHER_TEXT_SIZE 270 #endif 271 272 #define KYBER_SYM_SZ WC_ML_KEM_SYM_SZ 273 #define KYBER_SS_SZ WC_ML_KEM_SS_SZ 274 #define KYBER_MAKEKEY_RAND_SZ WC_ML_KEM_MAKEKEY_RAND_SZ 275 #define KYBER_ENC_RAND_SZ WC_ML_KEM_ENC_RAND_SZ 276 #define KYBER_POLY_SIZE WC_ML_KEM_POLY_SIZE 277 278 279 enum { 280 /* Types of Kyber keys. */ 281 WC_ML_KEM_512 = 0, 282 WC_ML_KEM_768 = 1, 283 WC_ML_KEM_1024 = 2, 284 285 MLKEM_KYBER = 0x10, 286 KYBER512 = 0 | MLKEM_KYBER, 287 KYBER768 = 1 | MLKEM_KYBER, 288 KYBER1024 = 2 | MLKEM_KYBER, 289 290 KYBER_LEVEL1 = KYBER512, 291 KYBER_LEVEL3 = KYBER768, 292 KYBER_LEVEL5 = KYBER1024, 293 294 /* Symmetric data size. */ 295 WC_ML_KEM_SYM_SZ = 32, 296 /* Shared secret size. */ 297 WC_ML_KEM_SS_SZ = 32, 298 /* Size of random required for making a key. */ 299 WC_ML_KEM_MAKEKEY_RAND_SZ = 2 * WC_ML_KEM_SYM_SZ, 300 /* Size of random required for encapsulation. */ 301 WC_ML_KEM_ENC_RAND_SZ = WC_ML_KEM_SYM_SZ, 302 303 /* Encoded polynomial size. */ 304 WC_ML_KEM_POLY_SIZE = 384, 305 }; 306 307 308 /* Different structures for different implementations. */ 309 typedef struct MlKemKey MlKemKey; 310 311 312 #ifdef __cplusplus 313 extern "C" { 314 #endif 315 316 WOLFSSL_API int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, 317 int devId); 318 WOLFSSL_API int wc_MlKemKey_Free(MlKemKey* key); 319 320 WOLFSSL_API int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng); 321 WOLFSSL_API int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key, 322 const unsigned char* rand, int len); 323 324 WOLFSSL_API int wc_MlKemKey_CipherTextSize(MlKemKey* key, word32* len); 325 WOLFSSL_API int wc_MlKemKey_SharedSecretSize(MlKemKey* key, word32* len); 326 327 WOLFSSL_API int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* ct, 328 unsigned char* ss, WC_RNG* rng); 329 WOLFSSL_API int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key, 330 unsigned char* ct, unsigned char* ss, const unsigned char* rand, int len); 331 WOLFSSL_API int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss, 332 const unsigned char* ct, word32 len); 333 334 WOLFSSL_API int wc_MlKemKey_DecodePrivateKey(MlKemKey* key, 335 const unsigned char* in, word32 len); 336 WOLFSSL_API int wc_MlKemKey_DecodePublicKey(MlKemKey* key, 337 const unsigned char* in, word32 len); 338 339 WOLFSSL_API int wc_MlKemKey_PrivateKeySize(MlKemKey* key, word32* len); 340 WOLFSSL_API int wc_MlKemKey_PublicKeySize(MlKemKey* key, word32* len); 341 WOLFSSL_API int wc_MlKemKey_EncodePrivateKey(MlKemKey* key, unsigned char* out, 342 word32 len); 343 WOLFSSL_API int wc_MlKemKey_EncodePublicKey(MlKemKey* key, unsigned char* out, 344 word32 len); 345 346 347 #define KyberKey MlKemKey 348 349 #define wc_KyberKey_Init(type, key, heap, devId) \ 350 wc_MlKemKey_Init(key, type, heap, devId) 351 #define wc_KyberKey_Free wc_MlKemKey_Free 352 #define wc_KyberKey_MakeKey wc_MlKemKey_MakeKey 353 #define wc_KyberKey_MakeKeyWithRandom wc_MlKemKey_MakeKeyWithRandom 354 #define wc_KyberKey_CipherTextSize wc_MlKemKey_CipherTextSize 355 #define wc_KyberKey_SharedSecretSize wc_MlKemKey_SharedSecretSize 356 #define wc_KyberKey_Encapsulate wc_MlKemKey_Encapsulate 357 #define wc_KyberKey_EncapsulateWithRandom wc_MlKemKey_EncapsulateWithRandom 358 #define wc_KyberKey_Decapsulate wc_MlKemKey_Decapsulate 359 #define wc_KyberKey_DecodePrivateKey wc_MlKemKey_DecodePrivateKey 360 #define wc_KyberKey_DecodePublicKey wc_MlKemKey_DecodePublicKey 361 #define wc_KyberKey_PrivateKeySize wc_MlKemKey_PrivateKeySize 362 #define wc_KyberKey_PublicKeySize wc_MlKemKey_PublicKeySize 363 #define wc_KyberKey_EncodePrivateKey wc_MlKemKey_EncodePrivateKey 364 #define wc_KyberKey_EncodePublicKey wc_MlKemKey_EncodePublicKey 365 366 367 #ifdef __cplusplus 368 } /* extern "C" */ 369 #endif 370 371 #endif /* WOLFSSL_HAVE_MLKEM */ 372 373 #endif /* WOLF_CRYPT_MLKEM_H */ 374