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)
21extern "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.
42OPENSSL_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.
51OPENSSL_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|.
57OPENSSL_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 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.
77OPENSSL_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// allocation failure.
83OPENSSL_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.
90OPENSSL_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.
99OPENSSL_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”.
116enum 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.
130OPENSSL_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.
136OPENSSL_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.
150OPENSSL_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.
179OPENSSL_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
189extern "C++" {
190
191BSSL_NAMESPACE_BEGIN
192
193BORINGSSL_MAKE_DELETER(SPAKE2_CTX, SPAKE2_CTX_free)
194
195BSSL_NAMESPACE_END
196
197} // extern C++
198
199#endif
200
201#endif // OPENSSL_HEADER_CURVE25519_H
202