diff options
| author | pukkamustard <pukkamustard@posteo.net> | 2021-02-05 21:02:47 +0100 |
|---|---|---|
| committer | pukkamustard <pukkamustard@posteo.net> | 2021-02-05 21:11:01 +0100 |
| commit | 5628804d6884232fe28fb8d5ead74197b52cde6d (patch) | |
| tree | 4724af0b0d39f07a724c55d28d925654a3290039 /vendor/doc/html/crypto_check_init_custom_hash.html | |
| parent | 6cef88d8d028db077e1b4e48a390d4648966536d (diff) | |
initial working commit
Diffstat (limited to 'vendor/doc/html/crypto_check_init_custom_hash.html')
| -rw-r--r-- | vendor/doc/html/crypto_check_init_custom_hash.html | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/vendor/doc/html/crypto_check_init_custom_hash.html b/vendor/doc/html/crypto_check_init_custom_hash.html new file mode 100644 index 0000000..9976495 --- /dev/null +++ b/vendor/doc/html/crypto_check_init_custom_hash.html @@ -0,0 +1,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> |