197 lines
9.2 KiB
HTML
197 lines
9.2 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_HMAC_SHA512(3MONOCYPHER)</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<table class="head">
|
||
|
|
<tr>
|
||
|
|
<td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td>
|
||
|
|
<td class="head-vol">3MONOCYPHER</td>
|
||
|
|
<td class="head-rtitle">CRYPTO_HMAC_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_hmac_sha512</b>,
|
||
|
|
<b class="Nm" title="Nm">crypto_hmac_sha512_init</b>,
|
||
|
|
<b class="Nm" title="Nm">crypto_hmac_sha512_update</b>,
|
||
|
|
<b class="Nm" title="Nm">crypto_hmac_sha512_final</b> —
|
||
|
|
<span class="Nd" title="Nd">cryptographic hash-based message authentication
|
||
|
|
code with SHA-512</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-ed25519.h</a>></b>
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<var class="Ft" title="Ft">void</var>
|
||
|
|
<br/>
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t
|
||
|
|
hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>,
|
||
|
|
<var class="Fa" title="Fa">size_t key_size</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_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx
|
||
|
|
*ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>,
|
||
|
|
<var class="Fa" title="Fa">size_t key_size</var>);
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<var class="Ft" title="Ft">void</var>
|
||
|
|
<br/>
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_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_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx
|
||
|
|
*ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>);
|
||
|
|
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
||
|
|
HMAC with SHA-512 is a cryptographically secure message authentication code
|
||
|
|
(MAC), provided to enable compatibility with other cryptographic systems. It
|
||
|
|
is generally recommended to use
|
||
|
|
<a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a>
|
||
|
|
instead, as it performs faster on x86_64 CPUs.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
The arguments are:
|
||
|
|
<dl class="Bl-tag">
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt>
|
||
|
|
<dd class="It-tag">The output MAC, which is always 64 bytes long.</dd>
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">key</var></dt>
|
||
|
|
<dd class="It-tag">Some secret key. One cannot predict the final hash without
|
||
|
|
it. Users may want to wipe the key with
|
||
|
|
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
||
|
|
once they are done with it.</dd>
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt>
|
||
|
|
<dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes.
|
||
|
|
32 is a good default. Keys longer than 128 bytes will be reduced to 64
|
||
|
|
bytes by hashing the key with SHA-512.</dd>
|
||
|
|
<dt class="It-tag"> </dt>
|
||
|
|
<dd class="It-tag"> </dd>
|
||
|
|
<dt class="It-tag"><var class="Fa" title="Fa">message</var></dt>
|
||
|
|
<dd class="It-tag">The message to compute the HMAC for. May overlap with
|
||
|
|
<var class="Fa" title="Fa">hmac</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"> </dt>
|
||
|
|
<dd class="It-tag"> </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_hmac_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_hmac_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_hmac_sha512_final</b>(), which produces
|
||
|
|
the final hash. The
|
||
|
|
<var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically
|
||
|
|
wiped upon finalisation.</li>
|
||
|
|
</ul>
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that
|
||
|
|
performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(),
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>().
|
||
|
|
<div class="Pp"></div>
|
||
|
|
MACs may be truncated safely down to at most 16 bytes; the
|
||
|
|
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>,
|
||
|
|
<a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>,
|
||
|
|
and
|
||
|
|
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
|
||
|
|
functions can be used to to compare (possibly truncated) MACs.
|
||
|
|
<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>
|
||
|
|
The following examples assume the existence of
|
||
|
|
<b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer
|
||
|
|
with cryptographically secure random bytes. If
|
||
|
|
<b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system,
|
||
|
|
see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
|
||
|
|
advice about how to generate cryptographically secure random bytes.
|
||
|
|
<div class="Pp"></div>
|
||
|
|
Computing a message authentication code all at once:
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<div class="Bd" style="margin-left: 5.00ex;">
|
||
|
|
<pre class="Li">
|
||
|
|
uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */
|
||
|
|
uint8_t key [32]; /* Key (at least 1 byte) */
|
||
|
|
uint8_t message[10] = "Lorem ipsu"; /* Message to authenticate */
|
||
|
|
arc4random_buf(key, 32);
|
||
|
|
crypto_hmac_sha512(hash, key, 32, message, 500);
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(message, 500);
|
||
|
|
crypto_wipe(key, 32);
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="Pp"></div>
|
||
|
|
Computing a message authentication code incrementally:
|
||
|
|
<div class="Pp"></div>
|
||
|
|
<div class="Bd" style="margin-left: 5.00ex;">
|
||
|
|
<pre class="Li">
|
||
|
|
uint8_t hash [64]; /* Output hash (between 1 and 64 bytes) */
|
||
|
|
uint8_t key [32]; /* Key (at least 1 byte) */
|
||
|
|
uint8_t message[500] = {1}; /* Message to authenticate */
|
||
|
|
crypto_hmac_sha512_ctx ctx;
|
||
|
|
arc4random_buf(key, 32);
|
||
|
|
crypto_hmac_sha512_init(&ctx, key, 32);
|
||
|
|
/* Wipe the key */
|
||
|
|
crypto_wipe(key, 32);
|
||
|
|
for (size_t i = 0; i < 500; i += 100) {
|
||
|
|
crypto_hmac_sha512_update(&ctx, message + i, 100);
|
||
|
|
/* Wipe secrets if they are no longer needed */
|
||
|
|
crypto_wipe(message + i, 100);
|
||
|
|
}
|
||
|
|
crypto_hmac_sha512_final(&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_lock.html">crypto_lock(3monocypher)</a>,
|
||
|
|
<a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>,
|
||
|
|
<a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(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 HMAC with SHA-512. HMAC and SHA-512 itself are
|
||
|
|
described in RFC 6234; SHA-512 is also described in the Federal Information
|
||
|
|
Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1.
|
||
|
|
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
||
|
|
The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(),
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(),
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and
|
||
|
|
<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first
|
||
|
|
appeared in Monocypher 3.0.0.</div>
|
||
|
|
<table class="foot">
|
||
|
|
<tr>
|
||
|
|
<td class="foot-date">March 2, 2020</td>
|
||
|
|
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|