aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_sha512_init.html
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/doc/html/crypto_sha512_init.html')
-rw-r--r--vendor/doc/html/crypto_sha512_init.html179
1 files changed, 179 insertions, 0 deletions
diff --git a/vendor/doc/html/crypto_sha512_init.html b/vendor/doc/html/crypto_sha512_init.html
new file mode 100644
index 0000000..e69fc91
--- /dev/null
+++ b/vendor/doc/html/crypto_sha512_init.html
@@ -0,0 +1,179 @@
+<!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_SHA512(3MONOCYPHER)</title>
+</head>
+<body>
+<table class="head">
+ <tr>
+ <td class="head-ltitle">CRYPTO_SHA512(3MONOCYPHER)</td>
+ <td class="head-vol">3MONOCYPHER</td>
+ <td class="head-rtitle">CRYPTO_SHA512(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_sha512</b>,
+ <b class="Nm" title="Nm">crypto_sha512_init</b>,
+ <b class="Nm" title="Nm">crypto_sha512_update</b>,
+ <b class="Nm" title="Nm">crypto_sha512_final</b> &#x2014;
+ <span class="Nd" title="Nd">cryptographic hashing with the SHA-512
+ algorithm</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-ed25519.h</a>&gt;</b>
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_sha512</b>(<var class="Fa" title="Fa">uint8_t
+ hash[64]</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_sha512_init</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
+ *ctx</var>);
+<div class="Pp"></div>
+<var class="Ft" title="Ft">void</var>
+<br/>
+<b class="Fn" title="Fn">crypto_sha512_update</b>(<var class="Fa" title="Fa">crypto_sha512_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_sha512_final</b>(<var class="Fa" title="Fa">crypto_sha512_ctx
+ *ctx</var>, <var class="Fa" title="Fa">uint8_t hash[64]</var>);
+<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+SHA-512 is a cryptographically secure hash, provided to enable compatibility
+ with other cryptographic systems. It is generally recommended to use
+ <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
+ instead, as it both performs faster on x86_64 CPUs and lacks many of the
+ pitfalls of SHA-512.
+<div class="Pp"></div>
+Note that SHA-512 itself is not suitable for hashing passwords and deriving keys
+ from them; use the
+ <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a>
+ family of functions for that purpose instead.
+<div class="Pp"></div>
+SHA-512 is <i class="Em" title="Em">vulnerable to length extension attacks</i>;
+ using it as a message authentication code (MAC) algorithm or keyed hash
+ requires precautions. The
+ <a class="Xr" title="Xr" href="crypto_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>
+ family of functions provides HMAC with SHA-512. Use
+ <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
+ to compare MACs created this way.
+<div class="Pp"></div>
+The arguments 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">The output hash, which is always 64 bytes long.</dd>
+ <dt class="It-tag">&#x00A0;</dt>
+ <dd class="It-tag">&#x00A0;</dd>
+ <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt>
+ <dd class="It-tag">The message to hash. May overlap with
+ <var class="Fa" title="Fa">hash</var>. May be
+ <code class="Dv" title="Dv">NULL</code> if
+ <var class="Fa" title="Fa">message_size</var> is 0.</dd>
+ <dt class="It-tag">&#x00A0;</dt>
+ <dd class="It-tag">&#x00A0;</dd>
+ <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt>
+ <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in
+ bytes.</dd>
+</dl>
+<div class="Pp"></div>
+An incremental interface is provided. It is useful for handling streams of data
+ or large files without using too much memory. This interface uses three steps:
+<ul class="Bl-bullet">
+ <li class="It-bullet">initialisation with
+ <b class="Fn" title="Fn">crypto_sha512_init</b>(), which sets up a context
+ with the hashing parameters;</li>
+ <li class="It-bullet">update with
+ <b class="Fn" title="Fn">crypto_sha512_update</b>(), which hashes the
+ message chunk by chunk, and keep the intermediary result in the
+ context;</li>
+ <li class="It-bullet">and finalisation with
+ <b class="Fn" title="Fn">crypto_sha512_final</b>(), which produces the
+ final hash. The <var class="Ft" title="Ft">crypto_sha512_ctx</var> is
+ automatically wiped upon finalisation.</li>
+</ul>
+<div class="Pp"></div>
+<b class="Fn" title="Fn">crypto_sha512</b>() is a convenience function that
+ performs <b class="Fn" title="Fn">crypto_sha512_init</b>(),
+ <b class="Fn" title="Fn">crypto_sha512_update</b>(), and
+ <b class="Fn" title="Fn">crypto_sha512_final</b>().
+<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>
+Hashing a message all at once:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+uint8_t hash [64]; /* Output hash (64 bytes) */
+uint8_t message[12] = &quot;Lorem ipsum&quot;; /* Message to hash */
+crypto_sha512(hash, message, 12);
+</pre>
+</div>
+<div class="Pp"></div>
+Hashing a message incrementally:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+uint8_t hash [ 64]; /* Output hash (64 bytes) */
+uint8_t message[500] = {1}; /* Message to hash */
+crypto_sha512_ctx ctx;
+crypto_sha512_init(&amp;ctx);
+for (size_t i = 0; i &lt; 500; i += 100) {
+ crypto_sha512_update(&amp;ctx, message + i, 100);
+}
+crypto_sha512_final(&amp;ctx, hash);
+</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_hmac_sha512.html">crypto_hmac_sha512(3monocypher)</a>,
+ <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(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 SHA-512, described in RFC 6234 and the Federal
+ Information Processing Standard (FIPS) 180-4.
+<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
+The <b class="Fn" title="Fn">crypto_sha512</b>(),
+ <b class="Fn" title="Fn">crypto_sha512_init</b>(),
+ <b class="Fn" title="Fn">crypto_sha512_update</b>(), and
+ <b class="Fn" title="Fn">crypto_sha512_final</b>() functions first appeared in
+ Monocypher 0.3; they were not intended for use outside Monocypher itself and
+ thus undocumented. They became part of the official API in Monocypher 3.0.0.
+<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
+ CONSIDERATIONS</a></h1>
+SHA-512 is a general-purpose cryptographic hash function; this means that it is
+ not suited for hashing passwords and deriving cryptographic keys from
+ passwords in particular. While cryptographic keys usually have hundreds of
+ bits of entropy, passwords are often much less complex. When storing passwords
+ as hashes or when deriving keys from them, the goal is normally to prevent
+ attackers from quickly iterating all possible passwords. Because passwords
+ tend to be simple, it is important to artificially slow down attackers by
+ using especially computationally difficult hashing algorithms. Monocypher
+ therefore provides
+ <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a>
+ for password hashing and deriving keys from passwords.</div>
+<table class="foot">
+ <tr>
+ <td class="foot-date">February 5, 2020</td>
+ <td class="foot-os">Linux 4.15.0-106-generic</td>
+ </tr>
+</table>
+</body>
+</html>