path: root/vendor/doc/html/crypto_check_init_custom_hash.html
diff options
authorpukkamustard <pukkamustard@posteo.net>2021-02-05 21:02:47 +0100
committerpukkamustard <pukkamustard@posteo.net>2021-02-05 21:11:01 +0100
commit5628804d6884232fe28fb8d5ead74197b52cde6d (patch)
tree4724af0b0d39f07a724c55d28d925654a3290039 /vendor/doc/html/crypto_check_init_custom_hash.html
parent6cef88d8d028db077e1b4e48a390d4648966536d (diff)
initial working commit
Diffstat (limited to 'vendor/doc/html/crypto_check_init_custom_hash.html')
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>
+ <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"/>
+<table class="head">
+ <tr>
+ <td class="head-vol">3MONOCYPHER</td>
+ </tr>
+<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>
+<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>
+<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>
+<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;
+<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>
+<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)
+ 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;
+<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>