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, publicprivate 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 peers_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 #define ED25519_PRIVATE_KEY_LEN 64 67 #define ED25519_PUBLIC_KEY_LEN 32 68 #define ED25519_SIGNATURE_LEN 64 69 70 /* ED25519_keypair sets |out_public_key| and |out_private_key| to a freshly 71 * generated, publicprivate key pair. */ 72 OPENSSL_EXPORT void ED25519_keypair(uint8_t out_public_key[32], 73 uint8_t out_private_key[64]); 74 75 /* ED25519_sign sets |out_sig| to be a signature of |message_len| bytes from 76 * |message| using |private_key|. It returns one on success or zero on 77 * error. */ 78 OPENSSL_EXPORT int ED25519_sign(uint8_t out_sig[64], const uint8_t *message, 79 size_t message_len, 80 const uint8_t private_key[64]); 81 82 /* ED25519_verify returns one iff |signature| is a valid signature, by 83 * |public_key| of |message_len| bytes from |message|. It returns zero 84 * otherwise. */ 85 OPENSSL_EXPORT int ED25519_verify(const uint8_t *message, size_t message_len, 86 const uint8_t signature[64], 87 const uint8_t public_key[32]); 88 89 /* ED25519_keypair_from_seed calculates a public and private key from an 90 * Ed25519 seed. Seed values are not exposed by this API (although they 91 * happen to be the first 32 bytes of a private key) so this function is for 92 * interoperating with systems that may store just a seed instead of a full 93 * private key. */ 94 OPENSSL_EXPORT void ED25519_keypair_from_seed(uint8_t out_public_key[32], 95 uint8_t out_private_key[64], 96 const uint8_t seed[32]); 97 98 99 /* SPAKE2. 100 * 101 * SPAKE2 is a password-authenticated key-exchange. It allows two parties, 102 * who share a low-entropy secret (i.e. password), to agree on a shared key. 103 * An attacker can only make one guess of the password per execution of the 104 * protocol. 105 * 106 * See https://tools.ietf.org/html/draft-irtf-cfrg-spake2-02. */ 107 108 /* spake2_role_t enumerates the different roles in SPAKE2. The protocol 109 * requires that the symmetry of the two parties be broken so one participant 110 * must be Alice and the other be Bob. */ 111 enum spake2_role_t { 112 spake2_role_alice, 113 spake2_role_bob, 114 }; 115 116 /* SPAKE2_CTX_new creates a new |SPAKE2_CTX| (which can only be used for a 117 * single execution of the protocol). SPAKE2 requires the symmetry of the two 118 * parties to be broken which is indicated via |my_role| each party must pass 119 * a different value for this argument. 120 * 121 * The |my_name| and |their_name| arguments allow optional, opaque names to be 122 * bound into the protocol. For example MAC addresses, hostnames, usernames 123 * etc. These values are not exposed and can avoid context-confusion attacks 124 * when a password is shared between several devices. */ 125 OPENSSL_EXPORT SPAKE2_CTX *SPAKE2_CTX_new( 126 enum spake2_role_t my_role, 127 const uint8_t *my_name, size_t my_name_len, 128 const uint8_t *their_name, size_t their_name_len); 129 130 /* SPAKE2_CTX_free frees |ctx| and all the resources that it has allocated. */ 131 OPENSSL_EXPORT void SPAKE2_CTX_free(SPAKE2_CTX *ctx); 132 133 /* SPAKE2_MAX_MSG_SIZE is the maximum size of a SPAKE2 message. */ 134 #define SPAKE2_MAX_MSG_SIZE 32 135 136 /* SPAKE2_generate_msg generates a SPAKE2 message given |password|, writes 137 * it to |out| and sets |*out_len| to the number of bytes written. 138 * 139 * At most |max_out_len| bytes are written to |out| and, in order to ensure 140 * success, |max_out_len| should be at least |SPAKE2_MAX_MSG_SIZE| bytes. 141 * 142 * This function can only be called once for a given |SPAKE2_CTX|. 143 * 144 * It returns one on success and zero on error. */ 145 OPENSSL_EXPORT int SPAKE2_generate_msg(SPAKE2_CTX *ctx, uint8_t *out, 146 size_t *out_len, size_t max_out_len, 147 const uint8_t *password, 148 size_t password_len); 149 150 /* SPAKE2_MAX_KEY_SIZE is the maximum amount of key material that SPAKE2 will 151 * produce. */ 152 #define SPAKE2_MAX_KEY_SIZE 64 153 154 /* SPAKE2_process_msg completes the SPAKE2 exchange given the peer's message in 155 * |their_msg|, writes at most |max_out_key_len| bytes to |out_key| and sets 156 * |*out_key_len| to the number of bytes written. 157 * 158 * The resulting keying material is suitable for: 159 * a) Using directly in a key-confirmation step: i.e. each side could 160 * transmit a hash of their role, a channel-binding value and the key 161 * material to prove to the other side that they know the shared key. 162 * b) Using as input keying material to HKDF to generate a variety of subkeys 163 * for encryption etc. 164 * 165 * If |max_out_key_key| is smaller than the amount of key material generated 166 * then the key is silently truncated. If you want to ensure that no truncation 167 * occurs then |max_out_key| should be at least |SPAKE2_MAX_KEY_SIZE|. 168 * 169 * You must call |SPAKE2_generate_msg| on a given |SPAKE2_CTX| before calling 170 * this function. On successful return, |ctx| is complete and calling 171 * |SPAKE2_CTX_free| is the only acceptable operation on it. 172 * 173 * Returns one on success or zero on error. */ 174 OPENSSL_EXPORT int SPAKE2_process_msg(SPAKE2_CTX *ctx, uint8_t *out_key, 175 size_t *out_key_len, 176 size_t max_out_key_len, 177 const uint8_t *their_msg, 178 size_t their_msg_len); 179 180 181 #if defined(__cplusplus) 182 } /* extern C */ 183 184 extern "C++" { 185 186 namespace bssl { 187 188 BORINGSSL_MAKE_DELETER(SPAKE2_CTX, SPAKE2_CTX_free) 189 190 } // namespace bssl 191 192 } /* extern C++ */ 193 194 #endif 195 196 #endif /* OPENSSL_HEADER_CURVE25519_H */ 197
