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_KYBER_H 16 #define OPENSSL_HEADER_KYBER_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 #if defined(OPENSSL_UNSTABLE_EXPERIMENTAL_KYBER) 26 // This header implements experimental, draft versions of not-yet-standardized 27 // primitives. When the standard is complete, these functions will be removed 28 // and replaced with the final, incompatible standard version. They are 29 // available now for short-lived experiments, but must not be deployed anywhere 30 // durable, such as a long-lived key store. To use these functions define 31 // OPENSSL_UNSTABLE_EXPERIMENTAL_KYBER 32 33 // Kyber768. 34 // 35 // This implements the round-3 specification of Kyber, defined at 36 // https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf 37 38 39 // KYBER_public_key contains a Kyber768 public key. The contents of this 40 // object should never leave the address space since the format is unstable. 41 struct KYBER_public_key { 42 union { 43 uint8_t bytes[512 * (3 + 9) + 32 + 32]; 44 uint16_t alignment; 45 } opaque; 46 }; 47 48 // KYBER_private_key contains a Kyber768 private key. The contents of this 49 // object should never leave the address space since the format is unstable. 50 struct KYBER_private_key { 51 union { 52 uint8_t bytes[512 * (3 + 3 + 9) + 32 + 32 + 32]; 53 uint16_t alignment; 54 } opaque; 55 }; 56 57 // KYBER_PUBLIC_KEY_BYTES is the number of bytes in an encoded Kyber768 public 58 // key. 59 #define KYBER_PUBLIC_KEY_BYTES 1184 60 61 // KYBER_SHARED_SECRET_BYTES is the number of bytes in the Kyber768 shared 62 // secret. Although the round-3 specification has a variable-length output, the 63 // final ML-KEM construction is expected to use a fixed 32-byte output. To 64 // simplify the future transition, we apply the same restriction. 65 #define KYBER_SHARED_SECRET_BYTES 32 66 67 // KYBER_generate_key generates a random public/private key pair, writes the 68 // encoded public key to |out_encoded_public_key| and sets |out_private_key| to 69 // the private key. 70 OPENSSL_EXPORT void KYBER_generate_key( 71 uint8_t out_encoded_public_key[KYBER_PUBLIC_KEY_BYTES], 72 struct KYBER_private_key *out_private_key); 73 74 // KYBER_public_from_private sets |*out_public_key| to the public key that 75 // corresponds to |private_key|. (This is faster than parsing the output of 76 // |KYBER_generate_key| if, for some reason, you need to encapsulate to a key 77 // that was just generated.) 78 OPENSSL_EXPORT void KYBER_public_from_private( 79 struct KYBER_public_key *out_public_key, 80 const struct KYBER_private_key *private_key); 81 82 // KYBER_CIPHERTEXT_BYTES is number of bytes in the Kyber768 ciphertext. 83 #define KYBER_CIPHERTEXT_BYTES 1088 84 85 // KYBER_encap encrypts a random shared secret for |public_key|, writes the 86 // ciphertext to |out_ciphertext|, and writes the random shared secret to 87 // |out_shared_secret|. 88 OPENSSL_EXPORT void KYBER_encap( 89 uint8_t out_ciphertext[KYBER_CIPHERTEXT_BYTES], 90 uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], 91 const struct KYBER_public_key *public_key); 92 93 // KYBER_decap decrypts a shared secret from |ciphertext| using |private_key| 94 // and writes it to |out_shared_secret|. If |ciphertext| is invalid, 95 // |out_shared_secret| is filled with a key that will always be the same for the 96 // same |ciphertext| and |private_key|, but which appears to be random unless 97 // one has access to |private_key|. These alternatives occur in constant time. 98 // Any subsequent symmetric encryption using |out_shared_secret| must use an 99 // authenticated encryption scheme in order to discover the decapsulation 100 // failure. 101 OPENSSL_EXPORT void KYBER_decap( 102 uint8_t out_shared_secret[KYBER_SHARED_SECRET_BYTES], 103 const uint8_t ciphertext[KYBER_CIPHERTEXT_BYTES], 104 const struct KYBER_private_key *private_key); 105 106 107 // Serialisation of keys. 108 109 // KYBER_marshal_public_key serializes |public_key| to |out| in the standard 110 // format for Kyber public keys. It returns one on success or zero on allocation 111 // error. 112 OPENSSL_EXPORT int KYBER_marshal_public_key( 113 CBB *out, const struct KYBER_public_key *public_key); 114 115 // KYBER_parse_public_key parses a public key, in the format generated by 116 // |KYBER_marshal_public_key|, from |in| and writes the result to 117 // |out_public_key|. It returns one on success or zero on parse error or if 118 // there are trailing bytes in |in|. 119 OPENSSL_EXPORT int KYBER_parse_public_key( 120 struct KYBER_public_key *out_public_key, CBS *in); 121 122 // KYBER_marshal_private_key serializes |private_key| to |out| in the standard 123 // format for Kyber private keys. It returns one on success or zero on 124 // allocation error. 125 OPENSSL_EXPORT int KYBER_marshal_private_key( 126 CBB *out, const struct KYBER_private_key *private_key); 127 128 // KYBER_PRIVATE_KEY_BYTES is the length of the data produced by 129 // |KYBER_marshal_private_key|. 130 #define KYBER_PRIVATE_KEY_BYTES 2400 131 132 // KYBER_parse_private_key parses a private key, in the format generated by 133 // |KYBER_marshal_private_key|, from |in| and writes the result to 134 // |out_private_key|. It returns one on success or zero on parse error or if 135 // there are trailing bytes in |in|. 136 OPENSSL_EXPORT int KYBER_parse_private_key( 137 struct KYBER_private_key *out_private_key, CBS *in); 138 139 #endif // OPENSSL_UNSTABLE_EXPERIMENTAL_KYBER 140 141 142 #if defined(__cplusplus) 143 } // extern C 144 #endif 145 146 #endif // OPENSSL_HEADER_KYBER_H 147