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