268 lines
12 KiB
HTML
268 lines
12 KiB
HTML
|
<!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>
|