259 lines
13 KiB
HTML
259 lines
13 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_ARGON2I(3MONOCYPHER)</title>
|
|
</head>
|
|
<body>
|
|
<table class="head">
|
|
<tr>
|
|
<td class="head-ltitle">CRYPTO_ARGON2I(3MONOCYPHER)</td>
|
|
<td class="head-vol">3MONOCYPHER</td>
|
|
<td class="head-rtitle">CRYPTO_ARGON2I(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_argon2i</b> —
|
|
<span class="Nd" title="Nd">password key derivation</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_argon2i</b>(<var class="Fa" title="Fa">uint8_t
|
|
*hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>,
|
|
<var class="Fa" title="Fa">void *work_area</var>,
|
|
<var class="Fa" title="Fa">uint32_t nb_blocks</var>,
|
|
<var class="Fa" title="Fa">uint32_t nb_iterations</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *password</var>,
|
|
<var class="Fa" title="Fa">uint32_t password_size</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *salt</var>,
|
|
<var class="Fa" title="Fa">uint32_t salt_size</var>);
|
|
<div class="Pp"></div>
|
|
<var class="Ft" title="Ft">void</var>
|
|
<br/>
|
|
<b class="Fn" title="Fn">crypto_argon2i_general</b>(<var class="Fa" title="Fa">uint8_t
|
|
*hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>,
|
|
<var class="Fa" title="Fa">void *work_area</var>,
|
|
<var class="Fa" title="Fa">uint32_t nb_blocks</var>,
|
|
<var class="Fa" title="Fa">uint32_t nb_iterations</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *password</var>,
|
|
<var class="Fa" title="Fa">uint32_t password_size</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *salt</var>,
|
|
<var class="Fa" title="Fa">uint32_t salt_size</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *key</var>,
|
|
<var class="Fa" title="Fa">uint32_t key_size</var>,
|
|
<var class="Fa" title="Fa">const uint8_t *ad</var>,
|
|
<var class="Fa" title="Fa">uint32_t ad_size</var>);
|
|
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
|
Argon2i is a resource intensive password key derivation scheme optimised for the
|
|
typical x86-like processor. It runs in constant time with respect to the
|
|
contents of the password.
|
|
<div class="Pp"></div>
|
|
Typical applications are password checking (for online services), and key
|
|
derivation (for encryption). Derived keys can be used to encrypt, for example,
|
|
private keys or password databases.
|
|
<div class="Pp"></div>
|
|
The version provided by Monocypher has no threading support, so the degree of
|
|
parallelism is limited to 1. This is considered good enough for most purposes.
|
|
<div class="Pp"></div>
|
|
The arguments to <b class="Fn" title="Fn">crypto_argon2i</b>() 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">The output hash.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt>
|
|
<dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes.
|
|
This argument should be set to 32 or 64 for compatibility with the
|
|
<b class="Fn" title="Fn">crypto_verify*</b>() constant time comparison
|
|
functions.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">work_area</var></dt>
|
|
<dd class="It-tag">Temporary buffer for the algorithm, allocated by the
|
|
caller. It must be <var class="Fa" title="Fa">nb_blocks</var> ×
|
|
1024 bytes big, and suitably aligned for 64-bit integers. If you are not
|
|
sure how to allocate that buffer, just use
|
|
<b class="Fn" title="Fn">malloc</b>().
|
|
<div class="Pp"></div>
|
|
The work area is automatically wiped by
|
|
<b class="Fn" title="Fn">crypto_argon2i</b>().</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">nb_blocks</var></dt>
|
|
<dd class="It-tag">The number of blocks for the work area. Must be at least 8.
|
|
A value of 100000 (one hundred megabytes) is a good starting point. If the
|
|
computation takes too long, reduce this number. If it is too fast,
|
|
increase this number. If it is still too fast with all available memory,
|
|
increase <var class="Fa" title="Fa">nb_iterations</var>.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">nb_iterations</var></dt>
|
|
<dd class="It-tag">The number of iterations. It must be at least 1. A value of
|
|
3 is <i class="Em" title="Em">strongly</i> recommended; any value lower
|
|
than 3 enables significantly more efficient attacks.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">password</var></dt>
|
|
<dd class="It-tag">The password to hash. It should be wiped with
|
|
<a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
|
|
after being hashed.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">password_size</var></dt>
|
|
<dd class="It-tag">Length of <var class="Fa" title="Fa">password</var>, in
|
|
bytes.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">salt</var></dt>
|
|
<dd class="It-tag">A password salt. This should be filled with random bytes,
|
|
generated separately for each password to be hashed. See
|
|
<a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
|
|
advice about generating random bytes (use the operating system's random
|
|
number generator).</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">salt_size</var></dt>
|
|
<dd class="It-tag">Length of <var class="Fa" title="Fa">salt</var>, in bytes.
|
|
Must be at least 8. 16 is recommended.</dd>
|
|
</dl>
|
|
<div class="Pp"></div>
|
|
The output hash must not overlap with the work area, or it will be wiped along
|
|
with it. Any other overlap is permitted.
|
|
<div class="Pp"></div>
|
|
Use
|
|
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>,
|
|
<a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>
|
|
or
|
|
<a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
|
|
to compare password hashes to prevent timing attacks.
|
|
<div class="Pp"></div>
|
|
To select the <var class="Fa" title="Fa">nb_blocks</var> and
|
|
<var class="Fa" title="Fa">nb_iterations</var> parameters, it should first be
|
|
decided how long the computation should take. For user authentication, values
|
|
somewhere between half a second (convenient) and several seconds (paranoid)
|
|
are recommended. The computation should use as much memory as can be spared.
|
|
<div class="Pp"></div>
|
|
Since parameter selection depends on your hardware, some trial and error will be
|
|
required in order to determine the ideal settings. Three iterations and 100000
|
|
blocks (that is, one hundred megabytes of memory) is a good starting point.
|
|
Adjust <var class="Fa" title="Fa">nb_blocks</var> first. If using all
|
|
available memory is not slow enough, increase
|
|
<var class="Fa" title="Fa">nb_iterations</var>.
|
|
<div class="Pp"></div>
|
|
<b class="Fn" title="Fn">crypto_argon2i_general</b>() is a variant of
|
|
<b class="Fn" title="Fn">crypto_argon2i</b>() that supports keyed hashing and
|
|
hashing of additional data. The additional 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">key</var></dt>
|
|
<dd class="It-tag">A key to use in the hash. Can be
|
|
<code class="Dv" title="Dv">NULL</code> if
|
|
<var class="Fa" title="Fa">key_size</var> is zero. The key is generally
|
|
not needed, but it does have some uses. In the context of password
|
|
derivation, it would be stored separately from the password database, and
|
|
would remain secret even if an attacker were to steal the database. Note
|
|
that changing the key requires rehashing the user's password, which is
|
|
only possible upon user login.</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.
|
|
Must be zero if there is no key.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt>
|
|
<dd class="It-tag">Additional data. This is additional data that goes into the
|
|
hash, similar to the authenticated encryption with authenticated data
|
|
(AEAD) construction in
|
|
<a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>.
|
|
This most likely has no practical application but is exposed for the sake
|
|
of completeness. This parameter may be
|
|
<code class="Dv" title="Dv">NULL</code> if
|
|
<var class="Fa" title="Fa">ad_size</var> is zero.</dd>
|
|
<dt class="It-tag"> </dt>
|
|
<dd class="It-tag"> </dd>
|
|
<dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt>
|
|
<dd class="It-tag">Length of <var class="Fa" title="Fa">ad</var>, in bytes.
|
|
Must be zero if there is no additional data.</dd>
|
|
</dl>
|
|
<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 example assumes 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>
|
|
This example shows how to hash a password with the recommended baseline
|
|
parameters:
|
|
<div class="Pp"></div>
|
|
<div class="Bd" style="margin-left: 5.00ex;">
|
|
<pre class="Li">
|
|
uint8_t hash[32]; /* Output hash */
|
|
char *password = "Okay Password!"; /* User's password */
|
|
uint32_t password_size = 14; /* Password length */
|
|
uint8_t salt[16]; /* Random salt */
|
|
const uint32_t nb_blocks = 100000; /* 100 megabytes */
|
|
const uint32_t nb_iterations = 3; /* 3 iterations */
|
|
void *work_area = malloc(nb_blocks * 1024); /* Work area */
|
|
if (work_area == NULL) {
|
|
/* Handle malloc() failure */
|
|
/* Wipe secrets if they are no longer needed */
|
|
crypto_wipe(password, password_size);
|
|
} else {
|
|
arc4random_buf(salt, 16);
|
|
crypto_argon2i(hash, 32,
|
|
work_area, nb_blocks, nb_iterations,
|
|
(uint8_t *)password, password_size,
|
|
salt, 16);
|
|
/* Wipe secrets if they are no longer needed */
|
|
crypto_wipe(password, password_size);
|
|
free(work_area);
|
|
}
|
|
</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_lock.html">crypto_lock(3monocypher)</a>,
|
|
<a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(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 Argon2i. An RFC draft is being maintained.
|
|
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
|
|
The <b class="Fn" title="Fn">crypto_argon2i_general</b>() function first
|
|
appeared in Monocypher 0.1 but was called
|
|
<b class="Fn" title="Fn">crypto_argon2i</b>(); it was renamed to its current
|
|
name in Monocypher 1.1.0. The current
|
|
<b class="Fn" title="Fn">crypto_argon2i</b>() first appeared in Monocypher
|
|
1.1.0.
|
|
<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1>
|
|
Any deviation from the specified input and output length ranges results in
|
|
<b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are
|
|
correct.</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">April 8, 2020</td>
|
|
<td class="foot-os">Linux 4.15.0-106-generic</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|