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> —
<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
<<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_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 “outer
signing context”. 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"> </dt>
<dd class="It-tag"> </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"> </dt>
<dd class="It-tag"> </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"> </dt>
<dd class="It-tag"> </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"> </dt>
<dd class="It-tag"> </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"> </dt>
<dd class="It-tag"> </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(&ctx);
SHA512Update(&ctx, msg, len);
SHA512Final(hash, &ctx);
}
static void
my_init(void *ctx)
{
struct outer_ctx *octx = (struct outer_ctx *)ctx;
SHA512Init(&octx->hash_ctx);
}
static void
my_update(void *ctx, const uint8_t *msg, size_t len)
{
struct outer_ctx *octx = (struct outer_ctx *)ctx;
SHA512Update(&octx->hash_ctx, msg, len);
}
static void
my_final(void *ctx, uint8_t *hash)
{
struct outer_ctx *octx = (struct outer_ctx *)ctx;
SHA512Final(hash, &octx->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*)&ctx;
crypto_sign_init_first_pass_custom_hash(actx,
sk, NULL, &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, "theirs != mine\n");
return 1;
}
puts("ok");
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>
|
