aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_hidden_key_pair.html
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/doc/html/crypto_hidden_key_pair.html')
-rw-r--r--vendor/doc/html/crypto_hidden_key_pair.html234
1 files changed, 0 insertions, 234 deletions
diff --git a/vendor/doc/html/crypto_hidden_key_pair.html b/vendor/doc/html/crypto_hidden_key_pair.html
deleted file mode 100644
index bdbc6cb..0000000
--- a/vendor/doc/html/crypto_hidden_key_pair.html
+++ /dev/null
@@ -1,234 +0,0 @@
-<!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_CURVE_TO_HIDDEN(3MONOCYPHER)</title>
-</head>
-<body>
-<table class="head">
- <tr>
- <td class="head-ltitle">CRYPTO_CURVE_TO_HIDDEN(3MONOCYPHER)</td>
- <td class="head-vol">3MONOCYPHER</td>
- <td class="head-rtitle">CRYPTO_CURVE_TO_HIDDEN(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_curve_to_hidden</b>,
- <b class="Nm" title="Nm">crypto_hidden_to_curve</b>,
- <b class="Nm" title="Nm">crypto_hidden_key_pair</b> &#x2014;
- <span class="Nd" title="Nd">hiding of X25519 public keys</span>
-<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1>
-<b class="In" title="In">#include
- &lt;<a class="In" title="In">monocypher.h</a>&gt;</b>
-<div class="Pp"></div>
-<var class="Ft" title="Ft">int</var>
-<br/>
-<b class="Fn" title="Fn">crypto_curve_to_hidden</b>(<var class="Fa" title="Fa">uint8_t
- hidden[32]</var>, <var class="Fa" title="Fa">const uint8_t curve[32]</var>,
- <var class="Fa" title="Fa">uint8_t tweak</var>);
-<div class="Pp"></div>
-<var class="Ft" title="Ft">void</var>
-<br/>
-<b class="Fn" title="Fn">crypto_hidden_to_curve</b>(<var class="Fa" title="Fa">uint8_t
- curve[32]</var>, <var class="Fa" title="Fa">const uint8_t hidden[32]</var>);
-<div class="Pp"></div>
-<var class="Ft" title="Ft">void</var>
-<br/>
-<b class="Fn" title="Fn">crypto_hidden_key_pair</b>(<var class="Fa" title="Fa">uint8_t
- hidden[32]</var>, <var class="Fa" title="Fa">uint8_t secret_key[32]</var>,
- <var class="Fa" title="Fa">uint8_t seed[32]</var>);
-<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-These functions allow obfuscating X25519 public keys by making them appear
- effectively indistinguishable from random noise. This is of interest for key
- exchange protocols that require indistinguishability from randomness, such as
- padded uniform random blobs (PURBs). They are intended for ephemeral
- (short-lived, possibly just one-time) X25519 keys, not for long-term public
- keys. After an initial key exchange involving hidden keys, subsequent key
- exchange messages should be encrypted instead; see, for example, the Noise
- protocol. This is an <i class="Em" title="Em">advanced feature</i> &#x2013;
- unless you are implementing an protocol that requires indistinguishability of
- all communications from random noise, consider
- <a class="Xr" title="Xr" href="crypto_key_exchange_public_key.html">crypto_key_exchange_public_key(3monocypher)</a>
- instead.
-<div class="Pp"></div>
-For understanding what these functions do, it is important to note that a
- &#x201C;public key&#x201D; in this context refers to a
- <i class="Em" title="Em">point on Curve25519</i>. This also means that these
- functions are not compatible with
- <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>
- and related functions.
-<div class="Pp"></div>
-<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() takes a public key
- <var class="Fa" title="Fa">curve</var> and a
- <var class="Fa" title="Fa">tweak</var>, hiding the public key it so that it is
- effectively indistinguishable from random noise. Note that only
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a>
- or
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>
- can generate a suitable public key; the
- <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>
- function is insufficient. The <var class="Fa" title="Fa">tweak</var> must be
- chosen at random. Even then, this operation <i class="Em" title="Em">may</i>
- fail: Not all curve points are capable of being hidden. In this case,
- <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() must be tried again with
- a new key pair; the <var class="Fa" title="Fa">tweak</var> does not need to be
- changed. On average, two attempts are needed. Once a suitable public key has
- been found, <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() always
- succeeds for it. Given the same values for
- <var class="Fa" title="Fa">tweak</var> and
- <var class="Fa" title="Fa">curve</var>,
- <b class="Fn" title="Fn">crypto_curve_to_hidden</b>() yields the same output
- value <var class="Fa" title="Fa">hidden</var>.
-<div class="Pp"></div>
-<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() performs the inverse
- operation: It decodes a hidden point to a curve point on Curve25519.
-<div class="Pp"></div>
-<b class="Fn" title="Fn">crypto_hidden_key_pair</b>() is a convenience function
- that generates a secret key and its corresponding public key, which is
- effectively indistinguishable from random noise, from a random seed.
- <i class="Em" title="Em">The execution time of this function is
- unpredictable</i> because it may take many failures until a key pair could be
- generated successfully. <b class="Fn" title="Fn">crypto_hidden_key_pair</b>()
- uses
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a>
- internally; if code size is an important concern, its functionality can be
- replicated with
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>
- instead.
-<div class="Pp"></div>
-The arguments are:
-<dl class="Bl-tag">
- <dt class="It-tag">&#x00A0;</dt>
- <dd class="It-tag">&#x00A0;</dd>
- <dt class="It-tag"><var class="Fa" title="Fa">curve</var></dt>
- <dd class="It-tag">A point on the curve, which is a Curve25519 public key
- generated with either
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_fast.html">crypto_x25519_dirty_fast(3monocypher)</a>
- or
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>.</dd>
- <dt class="It-tag">&#x00A0;</dt>
- <dd class="It-tag">&#x00A0;</dd>
- <dt class="It-tag"><var class="Fa" title="Fa">hidden</var></dt>
- <dd class="It-tag">The hidden encoding of a point on the curve which is
- effectively indistinguishable from random.</dd>
- <dt class="It-tag">&#x00A0;</dt>
- <dd class="It-tag">&#x00A0;</dd>
- <dt class="It-tag"><var class="Fa" title="Fa">secret_key</var></dt>
- <dd class="It-tag">The secret key that was generated from the given
- <var class="Fa" title="Fa">seed</var>.</dd>
- <dt class="It-tag">&#x00A0;</dt>
- <dd class="It-tag">&#x00A0;</dd>
- <dt class="It-tag"><var class="Fa" title="Fa">seed</var></dt>
- <dd class="It-tag">A 32-byte random number from which to derive a key pair.
- 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). The <var class="Fa" title="Fa">seed</var> is wiped
- automatically.</dd>
- <dt class="It-tag">&#x00A0;</dt>
- <dd class="It-tag">&#x00A0;</dd>
- <dt class="It-tag"><var class="Fa" title="Fa">tweak</var></dt>
- <dd class="It-tag">A 1-byte random number, which influences the final output
- of <b class="Fn" title="Fn">crypto_curve_to_hidden</b>().</dd>
-</dl>
-<div class="Pp"></div>
-The <var class="Fa" title="Fa">hidden</var> and
- <var class="Fa" title="Fa">curve</var> arguments may overlap or point at the
- same buffer.
-<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
- VALUES</a></h1>
-<b class="Fn" title="Fn">crypto_curve_to_hidden</b>() returns 0 on success, -1
- if the given <var class="Fa" title="Fa">curve</var> argument is unsuitable for
- hiding.
-<div class="Pp"></div>
-<b class="Fn" title="Fn">crypto_hidden_to_curve</b>() and
- <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() return nothing; they
- cannot fail.
-<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
-Generate a key pair manually using
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(3monocypher)</a>
- instead of its fast variant:
-<div class="Pp"></div>
-<div class="Bd" style="margin-left: 5.00ex;">
-<pre class="Li">
-uint8_t sk [32]; /* Secret key output */
-uint8_t pk [32]; /* Hidden public key output */
-uint8_t tweak; /* Random tweak input */
-arc4random_buf(&amp;tweak, 1);
-for (;;) {
- arc4random_buf(sk, 32);
- crypto_x25519_dirty_small(pk, sk);
- if (crypto_curve_to_hidden(pk, pk, tweak) == 0)
- break;
-}
-/* Now save the secret key and send the hidden public key. */
-</pre>
-</div>
-<div class="Pp"></div>
-Performing a key exchange with the other party's public key having been hidden:
-<div class="Pp"></div>
-<div class="Bd" style="margin-left: 5.00ex;">
-<pre class="Li">
-uint8_t hidden_pk [32]; /* Their hidden public key */
-uint8_t their_pk [32]; /* Their unhidden public key */
-uint8_t your_sk [32]; /* Your secret key */
-uint8_t shared_key[32]; /* Shared session key */
-crypto_hidden_to_curve(their_pk, hidden_pk);
-crypto_key_exchange(shared_key, your_sk, their_pk);
-/* Wipe secrets if they are no longer needed */
-crypto_wipe(your_sk, 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="crypto_x25519.html">crypto_x25519(3monocypher)</a>,
- <a class="Xr" title="Xr" href="crypto_x25519_dirty_small.html">crypto_x25519_dirty_small(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>
-These functions implement the Elligator 2 mapping for Curve25519. This mapping
- is incompatible with both the hash-to-curve Internet draft and the
- implementation of Elligator 2 in libsodium. Elligator 2 was described in:
- <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>,
- <span class="RsA">Mike Hamburg</span>, <span class="RsA">Anna Krasnova</span>,
- and <span class="RsA">Tanja Lange</span>, <span class="RsT">Elligator:
- Elliptic-curve points indistinguishable from uniform random strings</span>,
- <i class="RsI">Association for Computing Machinery</i>, <i class="RsJ">CCS
- '13: Proceedings of the 2013 ACM SIGSAC conference on Computer &amp;
- communications security</i>, <span class="RsP">pp. 967&#x2013;980</span>,
- <span class="RsD">2013</span>.</cite>
-<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
-The <b class="Fn" title="Fn">crypto_curve_to_hidden</b>(),
- <b class="Fn" title="Fn">crypto_hidden_to_curve</b>(), and
- <b class="Fn" title="Fn">crypto_hidden_key_pair</b>() functions first appeared
- in Monocypher 3.1.0.
-<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
- CONSIDERATIONS</a></h1>
-The secret keys for the public keys fed into
- <b class="Fn" title="Fn">crypto_curve_to_hidden</b>()
- <b class="Sy" title="Sy">must be chosen randomly</b>, rather than
- deterministically. Otherwise, the timing information given by the required
- number of retries also leaks information on the secret keys.
-<div class="Pp"></div>
-These functions <i class="Em" title="Em">help</i> build highly
- difficult-to-analyze protocols, but are insufficient by themselves: Other
- metadata, such as the amount of bytes sent in a packet or the size of the
- 32-byte random-looking string that represents the curve point itself, can be
- very strong indicators of the use of cryptography. Consider using appropriate
- padding algorithms, such as PADME, and obscure other metadata as much as
- possible.</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>