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 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, public–private 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