1 /* Copyright (c) 2023, 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_CRYPTO_MLKEM_INTERNAL_H 16 #define OPENSSL_HEADER_CRYPTO_MLKEM_INTERNAL_H 17 18 #include <openssl/base.h> 19 #include <openssl/mlkem.h> 20 21 #if defined(__cplusplus) 22 extern "C" { 23 #endif 24 25 26 // MLKEM_ENCAP_ENTROPY is the number of bytes of uniformly random entropy 27 // necessary to encapsulate a secret. The entropy will be leaked to the 28 // decapsulating party. 29 #define MLKEM_ENCAP_ENTROPY 32 30 31 // MLKEM768_generate_key_external_seed is a deterministic function to create a 32 // pair of ML-KEM-768 keys, using the supplied seed. The seed needs to be 33 // uniformly random. This function is should only be used for tests, regular 34 // callers should use the non-deterministic |MLKEM768_generate_key| directly. 35 OPENSSL_EXPORT void MLKEM768_generate_key_external_seed( 36 uint8_t out_encoded_public_key[MLKEM768_PUBLIC_KEY_BYTES], 37 struct MLKEM768_private_key *out_private_key, 38 const uint8_t seed[MLKEM_SEED_BYTES]); 39 40 // MLKEM768_encap_external_entropy behaves like |MLKEM768_encap|, but uses 41 // |MLKEM_ENCAP_ENTROPY| bytes of |entropy| for randomization. The decapsulating 42 // side will be able to recover |entropy| in full. This function should only be 43 // used for tests, regular callers should use the non-deterministic 44 // |MLKEM768_encap| directly. 45 OPENSSL_EXPORT void MLKEM768_encap_external_entropy( 46 uint8_t out_ciphertext[MLKEM768_CIPHERTEXT_BYTES], 47 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 48 const struct MLKEM768_public_key *public_key, 49 const uint8_t entropy[MLKEM_ENCAP_ENTROPY]); 50 51 // MLKEM768_marshal_private_key serializes |private_key| to |out| in the 52 // NIST format for ML-KEM-768 private keys. It returns one on success or 53 // zero on allocation error. (Note that one can also save just the seed value 54 // produced by |MLKEM768_generate_key|, which is significantly smaller.) 55 OPENSSL_EXPORT int MLKEM768_marshal_private_key( 56 CBB *out, const struct MLKEM768_private_key *private_key); 57 58 // MLKEM1024_generate_key_external_seed is a deterministic function to create a 59 // pair of ML-KEM-1024 keys, using the supplied seed. The seed needs to be 60 // uniformly random. This function is should only be used for tests, regular 61 // callers should use the non-deterministic |MLKEM1024_generate_key| directly. 62 OPENSSL_EXPORT void MLKEM1024_generate_key_external_seed( 63 uint8_t out_encoded_public_key[MLKEM1024_PUBLIC_KEY_BYTES], 64 struct MLKEM1024_private_key *out_private_key, 65 const uint8_t seed[MLKEM_SEED_BYTES]); 66 67 // MLKEM1024_encap_external_entropy behaves like |MLKEM1024_encap|, but uses 68 // |MLKEM_ENCAP_ENTROPY| bytes of |entropy| for randomization. The 69 // decapsulating side will be able to recover |entropy| in full. This function 70 // should only be used for tests, regular callers should use the 71 // non-deterministic |MLKEM1024_encap| directly. 72 OPENSSL_EXPORT void MLKEM1024_encap_external_entropy( 73 uint8_t out_ciphertext[MLKEM1024_CIPHERTEXT_BYTES], 74 uint8_t out_shared_secret[MLKEM_SHARED_SECRET_BYTES], 75 const struct MLKEM1024_public_key *public_key, 76 const uint8_t entropy[MLKEM_ENCAP_ENTROPY]); 77 78 // MLKEM1024_marshal_private_key serializes |private_key| to |out| in the 79 // NIST format for ML-KEM-1024 private keys. It returns one on success or 80 // zero on allocation error. (Note that one can also save just the seed value 81 // produced by |MLKEM1024_generate_key|, which is significantly smaller.) 82 OPENSSL_EXPORT int MLKEM1024_marshal_private_key( 83 CBB *out, const struct MLKEM1024_private_key *private_key); 84 85 86 #if defined(__cplusplus) 87 } 88 #endif 89 90 #endif // OPENSSL_HEADER_CRYPTO_MLKEM_INTERNAL_H 91