165 lines
8.2 KiB
HTML
165 lines
8.2 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta charset="utf-8"/>
|
||
|
|
<style>
|
||
|
|
table.head, table.foot { width: 100%; }
|
||
|
|
td.head-rtitle, td.foot-os { text-align: right; }
|
||
|
|
td.head-vol { text-align: center; }
|
||
|
|
div.Pp { margin: 1ex 0ex; }
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
||
|
|
<title>CRYPTO_X25519(3MONOCYPHER)</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<table class="head">
|
||
|
|
<tr>
|
||
|
|
<td class="head-ltitle">CRYPTO_X25519(3MONOCYPHER)</td>
|
||
|
|
<td class="head-vol">3MONOCYPHER</td>
|
||
|
|
<td class="head-rtitle">CRYPTO_X25519(3MONOCYPHER)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="manual-text">
|
||
|
|
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
|
||
|
|
<b class="Nm" title="Nm">crypto_x25519</b>,
|
||
|
|
<b class="Nm" title="Nm">crypto_x25519_public_key</b> —
|
||
|
|
<span class="Nd" title="Nd">X25519 key exchange</span>
|
||
|
|
<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
||
|
|
<b class="In" title="In">#include
|
||
|
|
<<a class="In" title="In">monocypher.h</a>></b>
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<var class="Ft" title="Ft">void</var>
|
||
|
|
<br/>
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519</b>(<var class="Fa" title="Fa">uint8_t
|
||
|
|
raw_shared_secret[32]</var>, <var class="Fa" title="Fa">const uint8_t
|
||
|
|
your_secret_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
|
||
|
|
their_public_key[32]</var>);
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<var class="Ft" title="Ft">void</var>
|
||
|
|
<br/>
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519_public_key</b>(<var class="Fa" title="Fa">uint8_t
|
||
|
|
your_public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
|
||
|
|
your_secret_key[32]</var>);
|
||
|
|
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519</b>() computes a shared secret with
|
||
|
|
<var class="Fa" title="Fa">your_secret_key</var> and
|
||
|
|
<var class="Fa" title="Fa">their_public_key</var>. It is a low-level
|
||
|
|
primitive. Use
|
||
|
|
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>
|
||
|
|
unless you have a specific reason not to.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() is the same as
|
||
|
|
<a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a>.
|
||
|
|
It deterministically computes the public key from a random secret key.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
The arguments are:
|
||
|
|
<dl class="Bl-tag">
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">raw_shared_secret</var></dt>
|
||
|
|
<dd class="It-tag">The shared secret, known only to those who know a relevant
|
||
|
|
secret key (yours or theirs). It is not cryptographically random. Do not
|
||
|
|
use it directly as a key. Hash it with
|
||
|
|
<a class="Xr" title="Xr" href="crypto_chacha20_H.html">crypto_chacha20_H(3monocypher)</a>
|
||
|
|
or
|
||
|
|
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
|
||
|
|
first.</dd>
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">your_secret_key</var></dt>
|
||
|
|
<dd class="It-tag">A 32-byte secret random number. See
|
||
|
|
<a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
|
||
|
|
advice about generating random bytes (use the operating system's random
|
||
|
|
number generator).</dd>
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">their_public_key</var></dt>
|
||
|
|
<dd class="It-tag">The public key of the other party.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<var class="Fa" title="Fa">raw_shared_secret</var> and
|
||
|
|
<var class="Fa" title="Fa">your_secret_key</var> may overlap if your
|
||
|
|
secret is no longer required.</dd>
|
||
|
|
</dl>
|
||
|
|
<div class="Pp"></div>
|
||
|
|
Some protocols, such as some password-authenticated key exchange (PAKE)
|
||
|
|
protocols and oblivious pseudo-random functions (OPRF), may require
|
||
|
|
“contributory” behaviour, which ensures that no untrusted party
|
||
|
|
forces the shared secret to a known constant. If a protocol requires
|
||
|
|
contributory behaviour, compare the output of
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519</b>() to an all-zero buffer using
|
||
|
|
<a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>;
|
||
|
|
abort the protocol if the output and the all-zero buffer are equal.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
Do not use the same secret key for both key exchanges and signatures. The public
|
||
|
|
keys are different, and revealing both may leak information. If there really
|
||
|
|
is no room to store or derive two different secret keys, consider generating a
|
||
|
|
key pair for signatures and then converting it with
|
||
|
|
<a class="Xr" title="Xr" href="crypto_from_eddsa_private.html">crypto_from_eddsa_private(3monocypher)</a>
|
||
|
|
and
|
||
|
|
<a class="Xr" title="Xr" href="crypto_from_eddsa_public.html">crypto_from_eddsa_public(3monocypher)</a>.
|
||
|
|
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
|
||
|
|
VALUES</a></h1>
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519</b>() and
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() return nothing.
|
||
|
|
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
|
||
|
|
The following example assumes the existence of
|
||
|
|
<b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer
|
||
|
|
with cryptographically secure random bytes. If
|
||
|
|
<b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system,
|
||
|
|
see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
|
||
|
|
advice about how to generate cryptographically secure random bytes.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
Generate a pair of shared keys with your secret key and their public key. (This
|
||
|
|
can help nonce management for full duplex communications.)
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<div class="Bd" style="margin-left: 5.00ex;">
|
||
|
|
<pre class="Li">
|
||
|
|
const uint8_t their_pk [32]; /* Their public key */
|
||
|
|
uint8_t your_sk [32]; /* Your secret key */
|
||
|
|
uint8_t shared_secret[32]; /* Shared secret (NOT a key) */
|
||
|
|
arc4random_buf(your_sk, 32);
|
||
|
|
crypto_x25519(shared_secret, your_sk, their_pk);
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(your_sk, 32);
|
||
|
|
|
||
|
|
uint8_t shared_keys[64]; /* Two shared session keys */
|
||
|
|
crypto_blake2b(shared_keys, shared_secret, 32);
|
||
|
|
const uint8_t *key_1 = shared_keys; /* Shared key 1 */
|
||
|
|
const uint8_t *key_2 = shared_keys + 32; /* Shared key 2 */
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(shared_secret, 32);
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
|
||
|
|
ALSO</a></h1>
|
||
|
|
<a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
|
||
|
|
<a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>
|
||
|
|
<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
|
||
|
|
This function implements X25519, described in RFC 7748.
|
||
|
|
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||
|
|
The <b class="Fn" title="Fn">crypto_x25519</b>(), and
|
||
|
|
<b class="Fn" title="Fn">crypto_x25519_public_key</b>() functions first
|
||
|
|
appeared in Monocypher 0.1.
|
||
|
|
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
|
||
|
|
CONSIDERATIONS</a></h1>
|
||
|
|
If either of the long term secret keys leaks, it may compromise
|
||
|
|
<i class="Em" title="Em">all past messages</i>. This can be avoided by using
|
||
|
|
protocols that provide forward secrecy, such as the X3DH key agreement
|
||
|
|
protocol.
|
||
|
|
<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
|
||
|
|
DETAILS</a></h1>
|
||
|
|
The most significant bit of the public key is systematically ignored. It is not
|
||
|
|
needed because every public key should be smaller than 2^255-19, which fits in
|
||
|
|
255 bits. If another implementation of X25519 gives you a key that is not
|
||
|
|
fully reduced and has its high bit set, the computation will fail. On the
|
||
|
|
other hand, it also means you may use this bit for other purposes (such as
|
||
|
|
parity flipping for Ed25519 compatibility).</div>
|
||
|
|
<table class="foot">
|
||
|
|
<tr>
|
||
|
|
<td class="foot-date">March 31, 2020</td>
|
||
|
|
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|