legacy-libs/grpc/deps/grpc/third_party/boringssl/include/openssl/curve25519.h

   1 /* Copyright (c) 2015, 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_CURVE25519_H
  16 #define OPENSSL_HEADER_CURVE25519_H
  17
  18 #include <openssl/base.h>
  19
  20 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif
  23
  24
  25 // Curve25519.
  26 //
  27 // Curve25519 is an elliptic curve. See https://tools.ietf.org/html/rfc7748.
  28
  29
  30 // X25519.
  31 //
  32 // X25519 is the Diffie-Hellman primitive built from curve25519. It is
  33 // sometimes referred to as “curve25519”, but “X25519” is a more precise name.
  34 // See http://cr.yp.to/ecdh.html and https://tools.ietf.org/html/rfc7748.
  35
  36 #define X25519_PRIVATE_KEY_LEN 32
  37 #define X25519_PUBLIC_VALUE_LEN 32
  38 #define X25519_SHARED_KEY_LEN 32
  39
  40 // X25519_keypair sets |out_public_value| and |out_private_key| to a freshly
  41 // generated, public–private key pair.
  42 OPENSSL_EXPORT void X25519_keypair(uint8_t out_public_value[32],
  43                                    uint8_t out_private_key[32]);
  44
  45 // X25519 writes a shared key to |out_shared_key| that is calculated from the
  46 // given private key and the peer's public value. It returns one on success and
  47 // zero on error.
  48 //
  49 // Don't use the shared key directly, rather use a KDF and also include the two
  50 // public values as inputs.
  51 OPENSSL_EXPORT int X25519(uint8_t out_shared_key[32],
  52                           const uint8_t private_key[32],
  53                           const uint8_t peer_public_value[32]);
  54
  55 // X25519_public_from_private calculates a Diffie-Hellman public value from the
  56 // given private key and writes it to |out_public_value|.
  57 OPENSSL_EXPORT void X25519_public_from_private(uint8_t out_public_value[32],
  58                                                const uint8_t private_key[32]);
  59
  60
  61 // Ed25519.
  62 //
  63 // Ed25519 is a signature scheme using a twisted-Edwards curve that is
  64 // birationally equivalent to curve25519.
  65 //
  66 // Note that, unlike RFC 8032's formulation, our private key representation
  67 // includes a public key suffix to make multiple key signing operations with the
  68 // same key more efficient. The RFC 8032 key private key is referred to in this
  69 // implementation as the "seed" and is the first 32 bytes of our private key.
  70
  71 #define ED25519_PRIVATE_KEY_LEN 64
  72 #define ED25519_PUBLIC_KEY_LEN 32
  73 #define ED25519_SIGNATURE_LEN 64
  74
  75 // ED25519_keypair sets |out_public_key| and |out_private_key| to a freshly
  76 // generated, public–private key pair.
  77 OPENSSL_EXPORT void ED25519_keypair(uint8_t out_public_key[32],
  78                                     uint8_t out_private_key[64]);
  79
  80 // ED25519_sign sets |out_sig| to be a signature of |message_len| bytes from
  81 // |message| using |private_key|. It returns one on success or zero on
  82 // error.
  83 OPENSSL_EXPORT int ED25519_sign(uint8_t out_sig[64], const uint8_t *message,
  84                                 size_t message_len,
  85                                 const uint8_t private_key[64]);
  86
  87 // ED25519_verify returns one iff |signature| is a valid signature, by
  88 // |public_key| of |message_len| bytes from |message|. It returns zero
  89 // otherwise.
  90 OPENSSL_EXPORT int ED25519_verify(const uint8_t *message, size_t message_len,
  91                                   const uint8_t signature[64],
  92                                   const uint8_t public_key[32]);
  93
  94 // ED25519_keypair_from_seed calculates a public and private key from an
  95 // Ed25519 “seed”. Seed values are not exposed by this API (although they
  96 // happen to be the first 32 bytes of a private key) so this function is for
  97 // interoperating with systems that may store just a seed instead of a full
  98 // private key.
  99 OPENSSL_EXPORT void ED25519_keypair_from_seed(uint8_t out_public_key[32],
 100                                               uint8_t out_private_key[64],
 101                                               const uint8_t seed[32]);
 102
 103
 104 // SPAKE2.
 105 //
 106 // SPAKE2 is a password-authenticated key-exchange. It allows two parties,
 107 // who share a low-entropy secret (i.e. password), to agree on a shared key.
 108 // An attacker can only make one guess of the password per execution of the
 109 // protocol.
 110 //
 111 // See https://tools.ietf.org/html/draft-irtf-cfrg-spake2-02.
 112
 113 // spake2_role_t enumerates the different “roles” in SPAKE2. The protocol
 114 // requires that the symmetry of the two parties be broken so one participant
 115 // must be “Alice” and the other be “Bob”.
 116 enum spake2_role_t {
 117   spake2_role_alice,
 118   spake2_role_bob,
 119 };
 120
 121 // SPAKE2_CTX_new creates a new |SPAKE2_CTX| (which can only be used for a
 122 // single execution of the protocol). SPAKE2 requires the symmetry of the two
 123 // parties to be broken which is indicated via |my_role| – each party must pass
 124 // a different value for this argument.
 125 //
 126 // The |my_name| and |their_name| arguments allow optional, opaque names to be
 127 // bound into the protocol. For example MAC addresses, hostnames, usernames
 128 // etc. These values are not exposed and can avoid context-confusion attacks
 129 // when a password is shared between several devices.
 130 OPENSSL_EXPORT SPAKE2_CTX *SPAKE2_CTX_new(
 131     enum spake2_role_t my_role,
 132     const uint8_t *my_name, size_t my_name_len,
 133     const uint8_t *their_name, size_t their_name_len);
 134
 135 // SPAKE2_CTX_free frees |ctx| and all the resources that it has allocated.
 136 OPENSSL_EXPORT void SPAKE2_CTX_free(SPAKE2_CTX *ctx);
 137
 138 // SPAKE2_MAX_MSG_SIZE is the maximum size of a SPAKE2 message.
 139 #define SPAKE2_MAX_MSG_SIZE 32
 140
 141 // SPAKE2_generate_msg generates a SPAKE2 message given |password|, writes
 142 // it to |out| and sets |*out_len| to the number of bytes written.
 143 //
 144 // At most |max_out_len| bytes are written to |out| and, in order to ensure
 145 // success, |max_out_len| should be at least |SPAKE2_MAX_MSG_SIZE| bytes.
 146 //
 147 // This function can only be called once for a given |SPAKE2_CTX|.
 148 //
 149 // It returns one on success and zero on error.
 150 OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out,
 151                                        size_t *out_len, size_t max_out_len,
 152                                        const uint8_t *password,
 153                                        size_t password_len);
 154
 155 // SPAKE2_MAX_KEY_SIZE is the maximum amount of key material that SPAKE2 will
 156 // produce.
 157 #define SPAKE2_MAX_KEY_SIZE 64
 158
 159 // SPAKE2_process_msg completes the SPAKE2 exchange given the peer's message in
 160 // |their_msg|, writes at most |max_out_key_len| bytes to |out_key| and sets
 161 // |*out_key_len| to the number of bytes written.
 162 //
 163 // The resulting keying material is suitable for:
 164 //   a) Using directly in a key-confirmation step: i.e. each side could
 165 //      transmit a hash of their role, a channel-binding value and the key
 166 //      material to prove to the other side that they know the shared key.
 167 //   b) Using as input keying material to HKDF to generate a variety of subkeys
 168 //      for encryption etc.
 169 //
 170 // If |max_out_key_key| is smaller than the amount of key material generated
 171 // then the key is silently truncated. If you want to ensure that no truncation
 172 // occurs then |max_out_key| should be at least |SPAKE2_MAX_KEY_SIZE|.
 173 //
 174 // You must call |SPAKE2_generate_msg| on a given |SPAKE2_CTX| before calling
 175 // this function. On successful return, |ctx| is complete and calling
 176 // |SPAKE2_CTX_free| is the only acceptable operation on it.
 177 //
 178 // Returns one on success or zero on error.
 179 OPENSSL_EXPORT int SPAKE2_process_msg(SPAKE2_CTX *ctx, uint8_t *out_key,
 180                                       size_t *out_key_len,
 181                                       size_t max_out_key_len,
 182                                       const uint8_t *their_msg,
 183                                       size_t their_msg_len);
 184
 185
 186 #if defined(__cplusplus)
 187 }  // extern C
 188
 189 extern "C++" {
 190
 191 namespace bssl {
 192
 193 BORINGSSL_MAKE_DELETER(SPAKE2_CTX, SPAKE2_CTX_free)
 194
 195 }  // namespace bssl
 196
 197 }  // extern C++
 198
 199 #endif
 200
 201 #endif  // OPENSSL_HEADER_CURVE25519_H