aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_check_init_custom_hash.html
blob: 9976495c709cc3be3d6ca5e48cc18e035b612591 (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
<!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_CUSTOM_HASH(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS_CUSTOM_HASH(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS_CUSTOM_HASH(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_custom_hash</b>,
  <b class="Nm" title="Nm">crypto_sign_public_key_custom_hash</b>,
  <b class="Nm" title="Nm">crypto_check_init_custom_hash</b> &#x2014;
  <span class="Nd" title="Nd">public key signatures with custom hash
  functions</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_custom_hash</b>(<var class="Fa" title="Fa">crypto_sign_ctx_abstract
  *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>,
  <var class="Fa" title="Fa">const crypto_sign_vtable *hash</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_sign_public_key_custom_hash</b>(<var class="Fa" title="Fa">uint8_t
  public_key[32]</var>, <var class="Fa" title="Fa">const uint8_t
  secret_key[32]</var>, <var class="Fa" title="Fa">const crypto_sign_vtable
  *hash</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_check_init_custom_hash</b>(<var class="Fa" title="Fa">crypto_sign_ctx_abstract
  *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>,
  <var class="Fa" title="Fa">const crypto_sign_vtable *hash</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
These functions are variants of the
  <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(3monocypher)</a>
  family of functions: They provide the ability to replace the EdDSA hash
  function with any user-provided hash function.
<div class="Pp"></div>
<b class="Sy" title="Sy">This is a highly advanced feature</b>. Interoperability
  of public key signatures with other cryptographic libraries can normally be
  achieved by using
  <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>
  or
  <a class="Xr" title="Xr" href="crypto_ed25519_sign_init_first_pass.html">crypto_ed25519_sign_init_first_pass(3monocypher)</a>
  already. This interface is exposed only for completeness and to handle special
  situations (e.g. to use the hash function of the future winner of the NIST
  lightweight crypto competition on a device with highly constrained resources
  or taking advantage of hardware support for cryptographic hash functions).
  Whenever possible, these functions should be avoided.
<div class="Pp"></div>
To make available a custom hash algorithm for use with these functions, a
  <var class="Vt" title="Vt">crypto_sign_vtable</var> structure must be
  provided. It is defined as:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 0.00ex;">
<pre class="Li">
typedef struct { 
    void (*hash)(uint8_t hash[64], const uint8_t *message, 
                 size_t message_size); 
    void (*init  )(void *ctx); 
    void (*update)(void *ctx, const uint8_t *message, 
                   size_t message_size); 
    void (*final )(void *ctx, uint8_t hash[64]); 
    size_t ctx_size; 
} crypto_sign_vtable;
</pre>
</div>
<div class="Pp"></div>
The context argument to the functions shall be referred to as &#x201C;outer
  signing context&#x201D;. The outer signing context must contain a
  <var class="Vt" title="Vt">crypto_sign_ctx_abstract</var> as
  <i class="Em" title="Em">its first member</i>. Other than that, the outer
  signing context may be defined freely. Logically, it is required to contain
  some kind of hash context as well, else it cannot work as a custom hash
  function.
<div class="Pp"></div>
Because the calling code cannot know the real type of the outer signing context,
  it is cast to <var class="Vt" title="Vt">void *</var> when calling the hash
  functions in the vtable, but the <var class="Fa" title="Fa">ctx</var> argument
  to the functions in the vtable is always guaranteed to be the outer signing
  context.
<div class="Pp"></div>
The hash functions must not fail. If they somehow can fail, they have no way to
  propagate its error status, and thus the only ways to handle errors are to
  either assume an error never occurs (if reasonable), or to induce a crash in
  the code when an error occurs.
<div class="Pp"></div>
The fields of <var class="Vt" title="Vt">crypto_sign_vtable</var> 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">hash</var></dt>
  <dd class="It-tag">Function that computes a 64-byte hash for a given message
      and writes the computed hash to <var class="Fa" title="Fa">hash</var>. The
      output length <i class="Em" title="Em">must</i> be exactly 64 bytes. This
      will normally be constructed using the functions that provide the
      <var class="Fa" title="Fa">init</var>,
      <var class="Fa" title="Fa">update</var> and
      <var class="Fa" title="Fa">final</var> members.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">init</var></dt>
  <dd class="It-tag">Function that initialises the hash context of an outer
      signing context.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">update</var></dt>
  <dd class="It-tag">Function that updates the hash context of an outer signing
      context. It must be able to handle message sizes of at least 32
    bytes.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">final</var></dt>
  <dd class="It-tag">Function that finalises the hash context of an outer
      signing context and writes the computed hash to
      <var class="Fa" title="Fa">hash</var>. The output length
      <i class="Em" title="Em">must</i> be exactly 64 bytes. This function
      should wipe the hash context with
      <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
      if it contains pointers to objects outside the outer signing context.
      Monocypher takes care of wiping the outer signing context.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">ctx_size</var></dt>
  <dd class="It-tag">The size of the outer signing context as determined by
      <b class="Fn" title="Fn">sizeof</b>().</dd>
</dl>
<div class="Pp"></div>
The functions indicated in the
  <var class="Vt" title="Vt">crypto_sign_vtable</var> must be thread-safe if any
  of Monocypher's signing functions are accessed from multiple threads.
<div class="Pp"></div>
After calling
  <b class="Fn" title="Fn">crypto_sign_init_first_pass_custom_hash</b>() or
  <b class="Fn" title="Fn">crypto_check_init_custom_hash</b>(), the
  <a class="Xr" title="Xr" href="crypto_sign_update.html">crypto_sign_update(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sign_final.html">crypto_sign_final(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sign_init_second_pass.html">crypto_sign_init_second_pass(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_check_update.html">crypto_check_update(3monocypher)</a>,
  and
  <a class="Xr" title="Xr" href="crypto_check_final.html">crypto_check_final(3monocypher)</a>
  functions can be used as usual. They will call into the hash vtable as
  required. The same security considerations and semantics apply.
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
These functions return nothing.
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
Defining and using a custom implementation of SHA-512 and crudely checking its
  results against
  <a class="Xr" title="Xr" href="crypto_ed25519_sign.html">crypto_ed25519_sign(3monocypher)</a>:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
struct outer_ctx { 
    crypto_sign_ctx_abstract sctx; 
    SHA2_CTX hash_ctx; 
}; 
 
static void 
my_hash(uint8_t hash[64], const uint8_t *msg, size_t len) 
{ 
    SHA2_CTX ctx; 
    SHA512Init(&amp;ctx); 
    SHA512Update(&amp;ctx, msg, len); 
    SHA512Final(hash, &amp;ctx); 
} 
 
static void 
my_init(void *ctx) 
{ 
    struct outer_ctx *octx = (struct outer_ctx *)ctx; 
    SHA512Init(&amp;octx-&gt;hash_ctx); 
} 
 
static void 
my_update(void *ctx, const uint8_t *msg, size_t len) 
{ 
    struct outer_ctx *octx = (struct outer_ctx *)ctx; 
    SHA512Update(&amp;octx-&gt;hash_ctx, msg, len); 
} 
 
static void 
my_final(void *ctx, uint8_t *hash) 
{ 
    struct outer_ctx *octx = (struct outer_ctx *)ctx; 
    SHA512Final(hash, &amp;octx-&gt;hash_ctx); 
} 
 
static const crypto_sign_vtable my_vtable = { 
    my_hash, 
    my_init, 
    my_update, 
    my_final, 
    sizeof(struct outer_ctx) 
}; 
 
int 
main(void) 
{ 
    uint8_t theirs[64], mine[64]; 
    uint8_t sk[32] = {0x01, 0x02, 0x03, 0x04}; 
    const uint8_t msg[] = { 
        0x00, 0x01, 0x02, 0x04 
    }; 
 
    crypto_ed25519_sign(theirs, sk, NULL, msg, sizeof(msg)); 
 
    struct outer_ctx ctx; 
    crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract*)&amp;ctx; 
    crypto_sign_init_first_pass_custom_hash(actx, 
                                            sk, NULL, &amp;my_vtable); 
    crypto_wipe(sk, sizeof(sk)); 
    crypto_sign_update(          actx, msg, sizeof(msg)); 
    crypto_sign_init_second_pass(actx); 
    crypto_sign_update(          actx, msg, sizeof(msg)); 
    crypto_sign_final(           actx, mine); 
 
    if (crypto_verify64(theirs, mine) != 0) { 
        fprintf(stderr, &quot;theirs != mine\n&quot;); 
        return 1; 
    } 
    puts(&quot;ok&quot;); 
    return 0; 
}
</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_sha512.html">crypto_sha512(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sign_init_first_pass.html">crypto_sign_init_first_pass(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="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_sign_init_first_pass_custom_hash</b>(),
  <b class="Fn" title="Fn">crypto_sign_public_key_custom_hash</b>(),
  <b class="Fn" title="Fn">crypto_check_init_first_pass_custom_hash</b>()
  functions first appeared in Monocypher 3.0.0.</div>
<table class="foot">
  <tr>
    <td class="foot-date">December 28, 2019</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>