1 // Copyright 2023 The BoringSSL Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_CRYPTO_KYBER_INTERNAL_H 16 #define OPENSSL_HEADER_CRYPTO_KYBER_INTERNAL_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // Kyber is the pre-standard version of ML-KEM. This was once exported as public 26 // API, but is now internal and only used by libssl. It will be removed entirely 27 // in the future. 28 // 29 // This implements the round-3 specification of Kyber, defined at 30 // https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf 31 32 // KYBER_public_key contains a Kyber768 public key. The contents of this 33 // object should never leave the address space since the format is unstable. 34 struct KYBER_public_key { 35 union { 36 uint8_t bytes[512 * (3 + 9) + 32 + 32]; 37 uint16_t alignment; 38 } opaque; 39 }; 40 41 // KYBER_private_key contains a Kyber768 private key. The contents of this 42 // object should never leave the address space since the format is unstable. 43 struct KYBER_private_key { 44 union { 45 uint8_t bytes[512 * (3 + 3 + 9) + 32 + 32 + 32]; 46 uint16_t alignment; 47 } opaque; 48 }; 49 50 // KYBER_PUBLIC_KEY_BYTES is the number of bytes in an encoded Kyber768 public 51 // key. 52 #define KYBER_PUBLIC_KEY_BYTES 1184 53 54 // KYBER_SHARED_SECRET_BYTES is the number of bytes in the Kyber768 shared 55 // secret. Although the round-3 specification has a variable-length output, the 56 // final ML-KEM construction is expected to use a fixed 32-byte output. To 57 // simplify the future transition, we apply the same restriction. 58 #define KYBER_SHARED_SECRET_BYTES 32 59 60 // KYBER_generate_key generates a random public/private key pair, writes the 61 // encoded public key to |out_encoded_public_key| and sets |out_private_key| to 62 // the private key. 63 OPENSSL_EXPORT void KYBER_generate_key( 64 uint8_t out_encoded_public_key[KYBER_PUBLIC_KEY_BYTES], 65 struct KYBER_private_key *out_private_key); 66 67 // KYBER_public_from_private sets |*out_public_key| to the public key that 68 // corresponds to |private_key|. (This is faster than parsing the output of 69 // |KYBER_generate_key| if, for some reason, you need to encapsulate to a key 70 // that was just generated.) 71 OPENSSL_EXPORT void KYBER_public_from_private( 72 struct KYBER_public_key *out_public_key, 73 const struct KYBER_private_key *private_key); 74 75 // KYBER_CIPHERTEXT_BYTES is number of bytes in the Kyber768 ciphertext. 76 #define KYBER_CIPHERTEXT_BYTES 1088 77 78 // KYBER_encap encrypts a random shared secret for |public_key|, writes the 79 // ciphertext to |out_ciphertext|, and writes the random shared secret to 80 // |out_shared_secret|. 81 OPENSSL_EXPORT void KYBER_encap( 82 uint8_t out_ciphertext[KYBER_CIPHERTEXT_BYTES], 83 uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], 84 const struct KYBER_public_key *public_key); 85 86 // KYBER_decap decrypts a shared secret from |ciphertext| using |private_key| 87 // and writes it to |out_shared_secret|. If |ciphertext| is invalid, 88 // |out_shared_secret| is filled with a key that will always be the same for the 89 // same |ciphertext| and |private_key|, but which appears to be random unless 90 // one has access to |private_key|. These alternatives occur in constant time. 91 // Any subsequent symmetric encryption using |out_shared_secret| must use an 92 // authenticated encryption scheme in order to discover the decapsulation 93 // failure. 94 OPENSSL_EXPORT void KYBER_decap( 95 uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], 96 const uint8_t ciphertext[KYBER_CIPHERTEXT_BYTES], 97 const struct KYBER_private_key *private_key); 98 99 100 // Serialisation of keys. 101 102 // KYBER_marshal_public_key serializes |public_key| to |out| in the standard 103 // format for Kyber public keys. It returns one on success or zero on allocation 104 // error. 105 OPENSSL_EXPORT int KYBER_marshal_public_key( 106 CBB *out, const struct KYBER_public_key *public_key); 107 108 // KYBER_parse_public_key parses a public key, in the format generated by 109 // |KYBER_marshal_public_key|, from |in| and writes the result to 110 // |out_public_key|. It returns one on success or zero on parse error or if 111 // there are trailing bytes in |in|. 112 OPENSSL_EXPORT int KYBER_parse_public_key( 113 struct KYBER_public_key *out_public_key, CBS *in); 114 115 // KYBER_marshal_private_key serializes |private_key| to |out| in the standard 116 // format for Kyber private keys. It returns one on success or zero on 117 // allocation error. 118 OPENSSL_EXPORT int KYBER_marshal_private_key( 119 CBB *out, const struct KYBER_private_key *private_key); 120 121 // KYBER_PRIVATE_KEY_BYTES is the length of the data produced by 122 // |KYBER_marshal_private_key|. 123 #define KYBER_PRIVATE_KEY_BYTES 2400 124 125 // KYBER_parse_private_key parses a private key, in the format generated by 126 // |KYBER_marshal_private_key|, from |in| and writes the result to 127 // |out_private_key|. It returns one on success or zero on parse error or if 128 // there are trailing bytes in |in|. 129 OPENSSL_EXPORT int KYBER_parse_private_key( 130 struct KYBER_private_key *out_private_key, CBS *in); 131 132 133 // Internal symbols. 134 135 // KYBER_ENCAP_ENTROPY is the number of bytes of uniformly random entropy 136 // necessary to encapsulate a secret. The entropy will be leaked to the 137 // decapsulating party. 138 #define KYBER_ENCAP_ENTROPY 32 139 140 // KYBER_GENERATE_KEY_ENTROPY is the number of bytes of uniformly random entropy 141 // necessary to generate a key. 142 #define KYBER_GENERATE_KEY_ENTROPY 64 143 144 // KYBER_generate_key_external_entropy is a deterministic function to create a 145 // pair of Kyber768 keys, using the supplied entropy. The entropy needs to be 146 // uniformly random generated. This function is should only be used for tests, 147 // regular callers should use the non-deterministic |KYBER_generate_key| 148 // directly. 149 OPENSSL_EXPORT void KYBER_generate_key_external_entropy( 150 uint8_t out_encoded_public_key[KYBER_PUBLIC_KEY_BYTES], 151 struct KYBER_private_key *out_private_key, 152 const uint8_t entropy[KYBER_GENERATE_KEY_ENTROPY]); 153 154 // KYBER_encap_external_entropy behaves like |KYBER_encap|, but uses 155 // |KYBER_ENCAP_ENTROPY| bytes of |entropy| for randomization. The decapsulating 156 // side will be able to recover |entropy| in full. This function should only be 157 // used for tests, regular callers should use the non-deterministic 158 // |KYBER_encap| directly. 159 OPENSSL_EXPORT void KYBER_encap_external_entropy( 160 uint8_t out_ciphertext[KYBER_CIPHERTEXT_BYTES], 161 uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], 162 const struct KYBER_public_key *public_key, 163 const uint8_t entropy[KYBER_ENCAP_ENTROPY]); 164 165 #if defined(__cplusplus) 166 } 167 #endif 168 169 #endif // OPENSSL_HEADER_CRYPTO_KYBER_INTERNAL_H 170