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