aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_curve_to_hidden.html
blob: bdbc6cbf4392a7814ee6d98ee7fa11a3cad8b6f3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
<!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>