aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_check_init.html
blob: 23bf4381fd8c01c26c6edb203e79fedd3ae26495 (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
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
<!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_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS(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_sign_init_first_pass</b>,
  <b class="Nm" title="Nm">crypto_sign_update</b>,
  <b class="Nm" title="Nm">crypto_sign_final</b>,
  <b class="Nm" title="Nm">crypto_sign_init_second_pass</b>,
  <b class="Nm" title="Nm">crypto_check_init</b>,
  <b class="Nm" title="Nm">crypto_check_update</b>,
  <b class="Nm" title="Nm">crypto_check_final</b> &#x2014;
  <span class="Nd" title="Nd">incremental public key signatures</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">void</var>
<br/>
<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t secret_key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t public_key[32]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_sign_update</b>(<var class="Fa" title="Fa">crypto_sign_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_sign_final</b>(<var class="Fa" title="Fa">crypto_sign_ctx
  *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx
  *ctx</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_check_init</b>(<var class="Fa" title="Fa">crypto_check_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t signature[64]</var>,
  <var class="Fa" title="Fa">const uint8_t public_key[32]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_check_update</b>(<var class="Fa" title="Fa">crypto_check_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">int</var>
<br/>
<b class="Fn" title="Fn">crypto_check_final</b>(<var class="Fa" title="Fa">crypto_check_ctx
  *ctx</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
These functions are variants of
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>
  and
  <a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>.
  Prefer those simpler functions if possible.
<div class="Pp"></div>
The arguments are the same as those described in
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>.
<div class="Pp"></div>
This incremental interface can be used to sign or verify messages too large to
  fit in a single buffer. The arguments are the same as the direct interface
  described in
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>.
<div class="Pp"></div>
The direct and incremental interface produce and accept the same signatures.
<div class="Pp"></div>
Signing is done in two passes. This requires five steps:
<ul class="Bl-bullet">
  <li class="It-bullet">Initialisation of the first pass with
      <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). The public key
      is optional, and will be recomputed if not provided. This recomputation
      doubles the execution time for short messages.</li>
  <li class="It-bullet">The first pass proper, with
      <b class="Fn" title="Fn">crypto_sign_update</b>().
      <b class="Sy" title="Sy">Under no circumstances must you forget the first
      pass</b>: Forgetting to call
      <b class="Fn" title="Fn">crypto_sign_update</b>() will appear to work in
      that it produces valid signatures, but also loses all security because
      attackers may now recover the secret key.</li>
  <li class="It-bullet">Initialisation of the second pass with
      <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>().</li>
  <li class="It-bullet">The second pass proper, with
      <b class="Fn" title="Fn">crypto_sign_update</b>(). The same update
      function is used for both passes.</li>
  <li class="It-bullet">Signature generation with
      <b class="Fn" title="Fn">crypto_sign_final</b>(). This also wipes the
      context.</li>
</ul>
<div class="Pp"></div>
Verification requires three steps:
<ul class="Bl-bullet">
  <li class="It-bullet">Initialisation with
      <b class="Fn" title="Fn">crypto_check_init</b>().</li>
  <li class="It-bullet">Update with
      <b class="Fn" title="Fn">crypto_check_update</b>().</li>
  <li class="It-bullet">Signature verification with
      <b class="Fn" title="Fn">crypto_check_final</b>().</li>
</ul>
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(),
  <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(),
  <b class="Fn" title="Fn">crypto_sign_update</b>(),
  <b class="Fn" title="Fn">crypto_sign_final</b>(),
  <b class="Fn" title="Fn">crypto_check_init</b>() and
  <b class="Fn" title="Fn">crypto_check_update</b>() return nothing.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_check_final</b>() returns 0 for legitimate
  messages and -1 for forgeries.
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
Sign a message:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t       sk       [ 32]; /* Secret key            */ 
const uint8_t pk       [ 32]; /* Public key (optional) */ 
const uint8_t message  [500]; /* Message to sign       */ 
uint8_t       signature[ 64]; /* Output signature      */ 
crypto_sign_ctx ctx; 
crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&amp;ctx, sk, pk); 
/* Wipe the secret key if no longer needed */ 
crypto_wipe(sk, 32); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_sign_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100); 
} 
crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&amp;ctx); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_sign_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100); 
} 
crypto_sign_final((crypto_sign_ctx_abstract*)&amp;ctx, signature);
</pre>
</div>
<div class="Pp"></div>
Check the above:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
const uint8_t pk       [ 32]; /* Public key         */ 
const uint8_t message  [500]; /* Message to sign    */ 
const uint8_t signature[ 64]; /* Signature to check */ 
crypto_check_ctx ctx; 
crypto_check_init((crypto_sign_ctx_abstract*)&amp;ctx, signature, pk); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_check_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100); 
} 
if (crypto_check_final((crypto_sign_ctx_abstract*)&amp;ctx)) { 
    /* Message is corrupted, abort processing */ 
} else { 
    /* Message is genuine */ 
}
</pre>
</div>
<div class="Pp"></div>
This interface can be used to mitigate attacks that leverage power analysis and
  fault injection (glitching) &#x2013; both of which require physical access and
  appropriate equipment &#x2013; by injecting additional randomness (at least 32
  bytes) and padding (to the hash function's block size, which is 128 bytes for
  all hash functions supported by Monocypher), of which 32 bytes are already
  inserted into the buffer by
  <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). Access to a
  cryptographically secure pseudo-random generator is a requirement for
  effective side channel mitigation. Signing a message with increased
  power-related side channel mitigations:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
const uint8_t message  [   500]; /* Message to sign         */ 
uint8_t       sk       [    32]; /* Secret key              */ 
const uint8_t pk       [    32]; /* Public key (optional)   */ 
uint8_t       signature[    64]; /* Output signature        */ 
uint8_t       buf      [128-32] = {0}; /* Mitigation buffer */ 
crypto_sign_ctx ctx; 
crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&amp;ctx; 
 
arc4random_buf(buf, 32); 
/* The rest of buf MUST be zeroes. */ 
 
crypto_sign_init_first_pass(actx, sk, pk); 
crypto_sign_update         (actx, buf, sizeof(buf)); 
crypto_sign_update         (actx, message, 500); 
 
crypto_sign_init_second_pass(actx); 
crypto_sign_update          (actx, message, 500); 
crypto_sign_final           (actx, signature); 
 
crypto_wipe(buf, 32); 
/* Wipe the secret key if no longer needed */ 
crypto_wipe(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_blake2b.html">crypto_blake2b(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(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 PureEdDSA with Curve25519 and Blake2b, as described in
  RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512.
<div class="Pp"></div>
The example for side channel mitigation follows the methodology outlined in
  I-D.draft-mattsson-cfrg-det-sigs-with-noise-02.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(),
  <b class="Fn" title="Fn">crypto_sign_update</b>(),
  <b class="Fn" title="Fn">crypto_sign_final</b>(),
  <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(),
  <b class="Fn" title="Fn">crypto_check_init</b>(),
  <b class="Fn" title="Fn">crypto_check_update</b>(), and
  <b class="Fn" title="Fn">crypto_check_final</b>() functions first appeared in
  Monocypher 1.1.0.
<div class="Pp"></div>
<b class="Sy" title="Sy">A critical security vulnerability</b> that caused
  all-zero signatures to be accepted was introduced in Monocypher 0.3; it was
  fixed in Monocypher 1.1.1 and 2.0.4.
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
  CONSIDERATIONS</a></h1>
Messages are not verified until the call to
  <b class="Fn" title="Fn">crypto_check_final</b>(). Messages may be stored
  before they are verified, but they cannot be
  <i class="Em" title="Em">trusted</i>. Processing untrusted messages increases
  the attack surface of the system. Doing so securely is hard. Do not process
  messages before calling <b class="Fn" title="Fn">crypto_check_final</b>().
<div class="Pp"></div>
When signing messages, the security considerations documented in
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>
  also apply. In particular, if power-related side channels are part of your
  threat model, note that there may still be other power-related side channels
  (such as if the CPU leaks information when an operation overflows a register)
  that must be considered.
<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
  DETAILS</a></h1>
EdDSA signatures require two passes that cannot be performed in parallel. There
  are ways around this limitation, but they all lower security in some way. For
  this reason, Monocypher does not support them.</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>