1 /* Copyright (c) 2018, 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_HRSS_H 16 #define OPENSSL_HEADER_HRSS_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 // HRSS 25 // 26 // HRSS is a structured-lattice-based post-quantum key encapsulation mechanism. 27 // The best exposition is https://eprint.iacr.org/2017/667.pdf although this 28 // implementation uses a different KEM construction based on 29 // https://eprint.iacr.org/2017/1005.pdf. 30 31 struct HRSS_private_key { 32 uint8_t opaque[1808]; 33 }; 34 35 struct HRSS_public_key { 36 uint8_t opaque[1424]; 37 }; 38 39 // HRSS_SAMPLE_BYTES is the number of bytes of entropy needed to generate a 40 // short vector. There are 701 coefficients, but the final one is always set to 41 // zero when sampling. Otherwise, we need one byte of input per coefficient. 42 #define HRSS_SAMPLE_BYTES (701 - 1) 43 // HRSS_GENERATE_KEY_BYTES is the number of bytes of entropy needed to generate 44 // an HRSS key pair. 45 #define HRSS_GENERATE_KEY_BYTES (HRSS_SAMPLE_BYTES + HRSS_SAMPLE_BYTES + 32) 46 // HRSS_ENCAP_BYTES is the number of bytes of entropy needed to encapsulate a 47 // session key. 48 #define HRSS_ENCAP_BYTES (HRSS_SAMPLE_BYTES + HRSS_SAMPLE_BYTES) 49 // HRSS_PUBLIC_KEY_BYTES is the number of bytes in a public key. 50 #define HRSS_PUBLIC_KEY_BYTES 1138 51 // HRSS_CIPHERTEXT_BYTES is the number of bytes in a ciphertext. 52 #define HRSS_CIPHERTEXT_BYTES 1138 53 // HRSS_KEY_BYTES is the number of bytes in a shared key. 54 #define HRSS_KEY_BYTES 32 55 // HRSS_POLY3_BYTES is the number of bytes needed to serialise a mod 3 56 // polynomial. 57 #define HRSS_POLY3_BYTES 140 58 #define HRSS_PRIVATE_KEY_BYTES \ 59 (HRSS_POLY3_BYTES * 2 + HRSS_PUBLIC_KEY_BYTES + 2 + 32) 60 61 // HRSS_generate_key is a deterministic function that outputs a public and 62 // private key based on the given entropy. 63 OPENSSL_EXPORT void HRSS_generate_key( 64 struct HRSS_public_key *out_pub, struct HRSS_private_key *out_priv, 65 const uint8_t input[HRSS_GENERATE_KEY_BYTES]); 66 67 // HRSS_encap is a deterministic function the generates and encrypts a random 68 // session key from the given entropy, writing those values to |out_shared_key| 69 // and |out_ciphertext|, respectively. 70 OPENSSL_EXPORT void HRSS_encap(uint8_t out_ciphertext[HRSS_CIPHERTEXT_BYTES], 71 uint8_t out_shared_key[HRSS_KEY_BYTES], 72 const struct HRSS_public_key *in_pub, 73 const uint8_t in[HRSS_ENCAP_BYTES]); 74 75 // HRSS_decap decrypts a session key from |ciphertext_len| bytes of 76 // |ciphertext|. If the ciphertext is valid, the decrypted key is written to 77 // |out_shared_key|. Otherwise the HMAC of |ciphertext| under a secret key (kept 78 // in |in_priv|) is written. If the ciphertext is the wrong length then it will 79 // leak which was done via side-channels. Otherwise it should perform either 80 // action in constant-time. 81 OPENSSL_EXPORT void HRSS_decap(uint8_t out_shared_key[HRSS_KEY_BYTES], 82 const struct HRSS_private_key *in_priv, 83 const uint8_t *ciphertext, 84 size_t ciphertext_len); 85 86 // HRSS_marshal_public_key serialises |in_pub| to |out|. 87 OPENSSL_EXPORT void HRSS_marshal_public_key( 88 uint8_t out[HRSS_PUBLIC_KEY_BYTES], const struct HRSS_public_key *in_pub); 89 90 // HRSS_parse_public_key sets |*out| to the public-key encoded in |in|. It 91 // returns true on success and zero on error. 92 OPENSSL_EXPORT int HRSS_parse_public_key( 93 struct HRSS_public_key *out, const uint8_t in[HRSS_PUBLIC_KEY_BYTES]); 94 95 96 #if defined(__cplusplus) 97 } // extern C 98 #endif 99 100 #endif // OPENSSL_HEADER_HRSS_H 101