aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_sign_init_second_pass.html
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/doc/html/crypto_sign_init_second_pass.html')
-rw-r--r--vendor/doc/html/crypto_sign_init_second_pass.html269
1 files changed, 269 insertions, 0 deletions
diff --git a/vendor/doc/html/crypto_sign_init_second_pass.html b/vendor/doc/html/crypto_sign_init_second_pass.html
new file mode 100644
index 0000000..23bf438
--- /dev/null
+++ b/vendor/doc/html/crypto_sign_init_second_pass.html
@@ -0,0 +1,269 @@
+<!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(3MONOCYPHER)</title>
+</head>
+<body>
+<table class="head">
+ <tr>
+ <td class="head-ltitle">CRYPTO_SIGN_INIT_FIRST_PASS(3MONOCYPHER)</td>
+ <td class="head-vol">3MONOCYPHER</td>
+ <td class="head-rtitle">CRYPTO_SIGN_INIT_FIRST_PASS(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</b>,
+ <b class="Nm" title="Nm">crypto_sign_update</b>,
+ <b class="Nm" title="Nm">crypto_sign_final</b>,
+ <b class="Nm" title="Nm">crypto_sign_init_second_pass</b>,
+ <b class="Nm" title="Nm">crypto_check_init</b>,
+ <b class="Nm" title="Nm">crypto_check_update</b>,
+ <b class="Nm" title="Nm">crypto_check_final</b> &#x2014;
+ <span class="Nd" title="Nd">incremental public key signatures</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</b>(<var class="Fa" title="Fa">crypto_sign_ctx
+ *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>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_sign_update</b>(<var class="Fa" title="Fa">crypto_sign_ctx
+ *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
+ <var class="Fa" title="Fa">size_t message_size</var>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_sign_final</b>(<var class="Fa" title="Fa">crypto_sign_ctx
+ *ctx</var>, <var class="Fa" title="Fa">uint8_t signature[64]</var>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(<var class="Fa" title="Fa">crypto_sign_ctx
+ *ctx</var>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_check_init</b>(<var class="Fa" title="Fa">crypto_check_ctx
+ *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>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_check_update</b>(<var class="Fa" title="Fa">crypto_check_ctx
+ *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
+ <var class="Fa" title="Fa">size_t message_size</var>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">int</var>
+<br/>
+<b class="Fn" title="Fn">crypto_check_final</b>(<var class="Fa" title="Fa">crypto_check_ctx
+ *ctx</var>);
+<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+These functions are variants of
+ <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>
+ and
+ <a class="Xr" title="Xr" href="crypto_check.html">crypto_check(3monocypher)</a>.
+ Prefer those simpler functions if possible.
+<div class="Pp"></div>
+The arguments are the same as those described in
+ <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>.
+<div class="Pp"></div>
+This incremental interface can be used to sign or verify messages too large to
+ fit in a single buffer. The arguments are the same as the direct interface
+ described in
+ <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>.
+<div class="Pp"></div>
+The direct and incremental interface produce and accept the same signatures.
+<div class="Pp"></div>
+Signing is done in two passes. This requires five steps:
+<ul class="Bl-bullet">
+ <li class="It-bullet">Initialisation of the first pass with
+ <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). The public key
+ is optional, and will be recomputed if not provided. This recomputation
+ doubles the execution time for short messages.</li>
+ <li class="It-bullet">The first pass proper, with
+ <b class="Fn" title="Fn">crypto_sign_update</b>().
+ <b class="Sy" title="Sy">Under no circumstances must you forget the first
+ pass</b>: Forgetting to call
+ <b class="Fn" title="Fn">crypto_sign_update</b>() will appear to work in
+ that it produces valid signatures, but also loses all security because
+ attackers may now recover the secret key.</li>
+ <li class="It-bullet">Initialisation of the second pass with
+ <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>().</li>
+ <li class="It-bullet">The second pass proper, with
+ <b class="Fn" title="Fn">crypto_sign_update</b>(). The same update
+ function is used for both passes.</li>
+ <li class="It-bullet">Signature generation with
+ <b class="Fn" title="Fn">crypto_sign_final</b>(). This also wipes the
+ context.</li>
+</ul>
+<div class="Pp"></div>
+Verification requires three steps:
+<ul class="Bl-bullet">
+ <li class="It-bullet">Initialisation with
+ <b class="Fn" title="Fn">crypto_check_init</b>().</li>
+ <li class="It-bullet">Update with
+ <b class="Fn" title="Fn">crypto_check_update</b>().</li>
+ <li class="It-bullet">Signature verification with
+ <b class="Fn" title="Fn">crypto_check_final</b>().</li>
+</ul>
+<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
+ VALUES</a></h1>
+<b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(),
+ <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(),
+ <b class="Fn" title="Fn">crypto_sign_update</b>(),
+ <b class="Fn" title="Fn">crypto_sign_final</b>(),
+ <b class="Fn" title="Fn">crypto_check_init</b>() and
+ <b class="Fn" title="Fn">crypto_check_update</b>() return nothing.
+<div class="Pp"></div>
+<b class="Fn" title="Fn">crypto_check_final</b>() returns 0 for legitimate
+ messages and -1 for forgeries.
+<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
+Sign a message:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+uint8_t sk [ 32]; /* Secret key */
+const uint8_t pk [ 32]; /* Public key (optional) */
+const uint8_t message [500]; /* Message to sign */
+uint8_t signature[ 64]; /* Output signature */
+crypto_sign_ctx ctx;
+crypto_sign_init_first_pass((crypto_sign_ctx_abstract*)&amp;ctx, sk, pk);
+/* Wipe the secret key if no longer needed */
+crypto_wipe(sk, 32);
+for (size_t i = 0; i &lt; 500; i += 100) {
+ crypto_sign_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100);
+}
+crypto_sign_init_second_pass((crypto_sign_ctx_abstract*)&amp;ctx);
+for (size_t i = 0; i &lt; 500; i += 100) {
+ crypto_sign_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100);
+}
+crypto_sign_final((crypto_sign_ctx_abstract*)&amp;ctx, signature);
+</pre>
+</div>
+<div class="Pp"></div>
+Check the above:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+const uint8_t pk [ 32]; /* Public key */
+const uint8_t message [500]; /* Message to sign */
+const uint8_t signature[ 64]; /* Signature to check */
+crypto_check_ctx ctx;
+crypto_check_init((crypto_sign_ctx_abstract*)&amp;ctx, signature, pk);
+for (size_t i = 0; i &lt; 500; i += 100) {
+ crypto_check_update((crypto_sign_ctx_abstract*)&amp;ctx, message + i, 100);
+}
+if (crypto_check_final((crypto_sign_ctx_abstract*)&amp;ctx)) {
+ /* Message is corrupted, abort processing */
+} else {
+ /* Message is genuine */
+}
+</pre>
+</div>
+<div class="Pp"></div>
+This interface can be used to mitigate attacks that leverage power analysis and
+ fault injection (glitching) &#x2013; both of which require physical access and
+ appropriate equipment &#x2013; by injecting additional randomness (at least 32
+ bytes) and padding (to the hash function's block size, which is 128 bytes for
+ all hash functions supported by Monocypher), of which 32 bytes are already
+ inserted into the buffer by
+ <b class="Fn" title="Fn">crypto_sign_init_first_pass</b>(). Access to a
+ cryptographically secure pseudo-random generator is a requirement for
+ effective side channel mitigation. Signing a message with increased
+ power-related side channel mitigations:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+const uint8_t message [ 500]; /* Message to sign */
+uint8_t sk [ 32]; /* Secret key */
+const uint8_t pk [ 32]; /* Public key (optional) */
+uint8_t signature[ 64]; /* Output signature */
+uint8_t buf [128-32] = {0}; /* Mitigation buffer */
+crypto_sign_ctx ctx;
+crypto_sign_ctx_abstract *actx = (crypto_sign_ctx_abstract *)&amp;ctx;
+
+arc4random_buf(buf, 32);
+/* The rest of buf MUST be zeroes. */
+
+crypto_sign_init_first_pass(actx, sk, pk);
+crypto_sign_update (actx, buf, sizeof(buf));
+crypto_sign_update (actx, message, 500);
+
+crypto_sign_init_second_pass(actx);
+crypto_sign_update (actx, message, 500);
+crypto_sign_final (actx, signature);
+
+crypto_wipe(buf, 32);
+/* Wipe the secret key if no longer needed */
+crypto_wipe(sk, 32);
+</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_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
+ <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
+ <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(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="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
+These functions implement PureEdDSA with Curve25519 and Blake2b, as described in
+ RFC 8032. This is the same as Ed25519, with Blake2b instead of SHA-512.
+<div class="Pp"></div>
+The example for side channel mitigation follows the methodology outlined in
+ I-D.draft-mattsson-cfrg-det-sigs-with-noise-02.
+<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</b>(),
+ <b class="Fn" title="Fn">crypto_sign_update</b>(),
+ <b class="Fn" title="Fn">crypto_sign_final</b>(),
+ <b class="Fn" title="Fn">crypto_sign_init_second_pass</b>(),
+ <b class="Fn" title="Fn">crypto_check_init</b>(),
+ <b class="Fn" title="Fn">crypto_check_update</b>(), and
+ <b class="Fn" title="Fn">crypto_check_final</b>() functions first appeared in
+ Monocypher 1.1.0.
+<div class="Pp"></div>
+<b class="Sy" title="Sy">A critical security vulnerability</b> that caused
+ all-zero signatures to be accepted was introduced in Monocypher 0.3; it was
+ fixed in Monocypher 1.1.1 and 2.0.4.
+<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
+ CONSIDERATIONS</a></h1>
+Messages are not verified until the call to
+ <b class="Fn" title="Fn">crypto_check_final</b>(). Messages may be stored
+ before they are verified, but they cannot be
+ <i class="Em" title="Em">trusted</i>. Processing untrusted messages increases
+ the attack surface of the system. Doing so securely is hard. Do not process
+ messages before calling <b class="Fn" title="Fn">crypto_check_final</b>().
+<div class="Pp"></div>
+When signing messages, the security considerations documented in
+ <a class="Xr" title="Xr" href="crypto_sign.html">crypto_sign(3monocypher)</a>
+ also apply. In particular, if power-related side channels are part of your
+ threat model, note that there may still be other power-related side channels
+ (such as if the CPU leaks information when an operation overflows a register)
+ that must be considered.
+<h1 class="Sh" title="Sh" id="IMPLEMENTATION_DETAILS"><a class="selflink" href="#IMPLEMENTATION_DETAILS">IMPLEMENTATION
+ DETAILS</a></h1>
+EdDSA signatures require two passes that cannot be performed in parallel. There
+ are ways around this limitation, but they all lower security in some way. For
+ this reason, Monocypher does not support them.</div>
+<table class="foot">
+ <tr>
+ <td class="foot-date">March 31, 2020</td>
+ <td class="foot-os">Linux 4.15.0-106-generic</td>
+ </tr>
+</table>
+</body>
+</html>