hrss.h (4342B)
1 // Copyright 2018 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_HRSS_H 16 #define OPENSSL_HEADER_HRSS_H 17 18 #include <openssl/base.h> // IWYU pragma: export 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. It returns one on success or zero 63 // on malloc failure. 64 OPENSSL_EXPORT int HRSS_generate_key( 65 struct HRSS_public_key *out_pub, struct HRSS_private_key *out_priv, 66 const uint8_t input[HRSS_GENERATE_KEY_BYTES]); 67 68 // HRSS_encap is a deterministic function the generates and encrypts a random 69 // session key from the given entropy, writing those values to |out_shared_key| 70 // and |out_ciphertext|, respectively. It returns one on success or zero on 71 // malloc failure. 72 OPENSSL_EXPORT int HRSS_encap(uint8_t out_ciphertext[HRSS_CIPHERTEXT_BYTES], 73 uint8_t out_shared_key[HRSS_KEY_BYTES], 74 const struct HRSS_public_key *in_pub, 75 const uint8_t in[HRSS_ENCAP_BYTES]); 76 77 // HRSS_decap decrypts a session key from |ciphertext_len| bytes of 78 // |ciphertext|. If the ciphertext is valid, the decrypted key is written to 79 // |out_shared_key|. Otherwise the HMAC of |ciphertext| under a secret key (kept 80 // in |in_priv|) is written. If the ciphertext is the wrong length then it will 81 // leak which was done via side-channels. Otherwise it should perform either 82 // action in constant-time. It returns one on success (whether the ciphertext 83 // was valid or not) and zero on malloc failure. 84 OPENSSL_EXPORT int HRSS_decap(uint8_t out_shared_key[HRSS_KEY_BYTES], 85 const struct HRSS_private_key *in_priv, 86 const uint8_t *ciphertext, size_t ciphertext_len); 87 88 // HRSS_marshal_public_key serialises |in_pub| to |out|. 89 OPENSSL_EXPORT void HRSS_marshal_public_key( 90 uint8_t out[HRSS_PUBLIC_KEY_BYTES], const struct HRSS_public_key *in_pub); 91 92 // HRSS_parse_public_key sets |*out| to the public-key encoded in |in|. It 93 // returns true on success and zero on error. 94 OPENSSL_EXPORT int HRSS_parse_public_key( 95 struct HRSS_public_key *out, const uint8_t in[HRSS_PUBLIC_KEY_BYTES]); 96 97 98 #if defined(__cplusplus) 99 } // extern C 100 #endif 101 102 #endif // OPENSSL_HEADER_HRSS_H