xwing.h (4419B)
1 // Copyright 2025 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_XWING_H 16 #define OPENSSL_HEADER_XWING_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // X-Wing. 26 // 27 // This implements the X-Wing key encapsulation mechanism from 28 // https://datatracker.ietf.org/doc/html/draft-connolly-cfrg-xwing-kem-06. 29 30 31 // XWING_private_key contains an X-Wing private key. The contents of this object 32 // should never leave the address space since the format is unstable. 33 struct XWING_private_key { 34 union { 35 uint8_t bytes[512 * (3 + 3 + 9) + 32 + 32 + 32 + 32 + 32]; 36 uint16_t alignment; 37 } opaque; 38 }; 39 40 // XWING_PUBLIC_KEY_BYTES is the number of bytes in an encoded X-Wing public 41 // key. 42 #define XWING_PUBLIC_KEY_BYTES 1216 43 44 // XWING_PRIVATE_KEY_BYTES is the number of bytes in an encoded X-Wing private 45 // key. 46 #define XWING_PRIVATE_KEY_BYTES 32 47 48 // XWING_CIPHERTEXT_BYTES is the number of bytes in the X-Wing ciphertext. 49 #define XWING_CIPHERTEXT_BYTES 1120 50 51 // XWING_SHARED_SECRET_BYTES is the number of bytes in an X-Wing shared secret. 52 #define XWING_SHARED_SECRET_BYTES 32 53 54 55 // XWING_generate_key generates a random public/private key pair, writes the 56 // encoded public key to |out_encoded_public_key| and the private key to 57 // |out_private_key|. Returns one on success and zero on error. 58 OPENSSL_EXPORT int XWING_generate_key( 59 uint8_t out_encoded_public_key[XWING_PUBLIC_KEY_BYTES], 60 struct XWING_private_key *out_private_key); 61 62 // XWING_public_from_private sets |out_encoded_public_key| to the public key 63 // that corresponds to |private_key|. Returns one on success and zero on error. 64 OPENSSL_EXPORT int XWING_public_from_private( 65 uint8_t out_encoded_public_key[XWING_PUBLIC_KEY_BYTES], 66 const struct XWING_private_key *private_key); 67 68 // XWING_encap encapsulates a random shared secret for |encoded_public_key|, 69 // writes the ciphertext to |out_ciphertext|, and writes the random shared 70 // secret to |out_shared_secret|. Returns one on success and zero on error. 71 OPENSSL_EXPORT int XWING_encap( 72 uint8_t out_ciphertext[XWING_CIPHERTEXT_BYTES], 73 uint8_t out_shared_secret[XWING_SHARED_SECRET_BYTES], 74 const uint8_t encoded_public_key[XWING_PUBLIC_KEY_BYTES]); 75 76 // XWING_encap_external_entropy encapsulates the shared secret for the given 77 // |eseed| entropy using |encoded_public_key|, writes the ciphertext to 78 // |out_ciphertext|, and writes the random shared secret to |out_shared_secret|. 79 // Returns one on success and zero on error. 80 OPENSSL_EXPORT int XWING_encap_external_entropy( 81 uint8_t out_ciphertext[XWING_CIPHERTEXT_BYTES], 82 uint8_t out_shared_secret[XWING_SHARED_SECRET_BYTES], 83 const uint8_t encoded_public_key[XWING_PUBLIC_KEY_BYTES], 84 const uint8_t eseed[64]); 85 86 // XWING_decap decapsulates a shared secret from |ciphertext| using 87 // |private_key| and writes it to |out_shared_secret|. Returns one on success 88 // and zero on error. 89 OPENSSL_EXPORT int XWING_decap( 90 uint8_t out_shared_secret[XWING_SHARED_SECRET_BYTES], 91 const uint8_t ciphertext[XWING_CIPHERTEXT_BYTES], 92 const struct XWING_private_key *private_key); 93 94 // Serialisation of keys. 95 96 // XWING_marshal_private_key serializes |private_key| to |out| in the standard 97 // format for X-Wing private keys. It returns one on success or zero on 98 // allocation error. 99 OPENSSL_EXPORT int XWING_marshal_private_key( 100 CBB *out, const struct XWING_private_key *private_key); 101 102 // XWING_parse_private_key parses a private key in the standard format for 103 // X-Wing private keys from |in| and writes the result to |out_public_key|. It 104 // returns one on success or zero on parse error or if there are trailing bytes 105 // in |in|. 106 OPENSSL_EXPORT int XWING_parse_private_key( 107 struct XWING_private_key *out_private_key, CBS *in); 108 109 110 #if defined(__cplusplus) 111 } // extern C 112 #endif 113 114 #endif // OPENSSL_HEADER_XWING_H