298 lines
9.2 KiB
Plaintext
298 lines
9.2 KiB
Plaintext
.\" This file is dual-licensed. Choose whichever you want.
|
||
.\"
|
||
.\" The first licence is a regular 2-clause BSD licence. The second licence
|
||
.\" is the CC-0 from Creative Commons. It is intended to release Monocypher
|
||
.\" to the public domain. The BSD licence serves as a fallback option.
|
||
.\"
|
||
.\" SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0
|
||
.\"
|
||
.\" ----------------------------------------------------------------------------
|
||
.\"
|
||
.\" Copyright (c) 2017-2019 Loup Vaillant
|
||
.\" Copyright (c) 2018 Michael Savage
|
||
.\" Copyright (c) 2017, 2019-2020 Fabio Scotoni
|
||
.\" All rights reserved.
|
||
.\"
|
||
.\"
|
||
.\" Redistribution and use in source and binary forms, with or without
|
||
.\" modification, are permitted provided that the following conditions are
|
||
.\" met:
|
||
.\"
|
||
.\" 1. Redistributions of source code must retain the above copyright
|
||
.\" notice, this list of conditions and the following disclaimer.
|
||
.\"
|
||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
.\" notice, this list of conditions and the following disclaimer in the
|
||
.\" documentation and/or other materials provided with the
|
||
.\" distribution.
|
||
.\"
|
||
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
.\"
|
||
.\" ----------------------------------------------------------------------------
|
||
.\"
|
||
.\" Written in 2017-2020 by Loup Vaillant, Michael Savage and Fabio Scotoni
|
||
.\"
|
||
.\" To the extent possible under law, the author(s) have dedicated all copyright
|
||
.\" and related neighboring rights to this software to the public domain
|
||
.\" worldwide. This software is distributed without any warranty.
|
||
.\"
|
||
.\" You should have received a copy of the CC0 Public Domain Dedication along
|
||
.\" with this software. If not, see
|
||
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
|
||
.\"
|
||
.Dd April 8, 2020
|
||
.Dt CRYPTO_ARGON2I 3MONOCYPHER
|
||
.Os
|
||
.Sh NAME
|
||
.Nm crypto_argon2i
|
||
.Nd password key derivation
|
||
.Sh SYNOPSIS
|
||
.In monocypher.h
|
||
.Ft void
|
||
.Fo crypto_argon2i
|
||
.Fa "uint8_t *hash"
|
||
.Fa "uint32_t hash_size"
|
||
.Fa "void *work_area"
|
||
.Fa "uint32_t nb_blocks"
|
||
.Fa "uint32_t nb_iterations"
|
||
.Fa "const uint8_t *password"
|
||
.Fa "uint32_t password_size"
|
||
.Fa "const uint8_t *salt"
|
||
.Fa "uint32_t salt_size"
|
||
.Fc
|
||
.Ft void
|
||
.Fo crypto_argon2i_general
|
||
.Fa "uint8_t *hash"
|
||
.Fa "uint32_t hash_size"
|
||
.Fa "void *work_area"
|
||
.Fa "uint32_t nb_blocks"
|
||
.Fa "uint32_t nb_iterations"
|
||
.Fa "const uint8_t *password"
|
||
.Fa "uint32_t password_size"
|
||
.Fa "const uint8_t *salt"
|
||
.Fa "uint32_t salt_size"
|
||
.Fa "const uint8_t *key"
|
||
.Fa "uint32_t key_size"
|
||
.Fa "const uint8_t *ad"
|
||
.Fa "uint32_t ad_size"
|
||
.Fc
|
||
.Sh DESCRIPTION
|
||
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.
|
||
.Pp
|
||
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.
|
||
.Pp
|
||
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.
|
||
.Pp
|
||
The arguments to
|
||
.Fn crypto_argon2i
|
||
are:
|
||
.Bl -tag -width Ds
|
||
.It Fa hash
|
||
The output hash.
|
||
.It Fa hash_size
|
||
Length of
|
||
.Fa hash ,
|
||
in bytes.
|
||
This argument should be set to 32 or 64 for compatibility with the
|
||
.Fn crypto_verify*
|
||
constant time comparison functions.
|
||
.It Fa work_area
|
||
Temporary buffer for the algorithm, allocated by the caller.
|
||
It must be
|
||
.Fa nb_blocks
|
||
× 1024 bytes big, and suitably aligned for 64-bit integers.
|
||
If you are not sure how to allocate that buffer, just use
|
||
.Fn malloc .
|
||
.Pp
|
||
The work area is automatically wiped by
|
||
.Fn crypto_argon2i .
|
||
.It Fa nb_blocks
|
||
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
|
||
.Fa nb_iterations .
|
||
.It Fa nb_iterations
|
||
The number of iterations.
|
||
It must be at least 1.
|
||
A value of 3 is
|
||
.Em strongly
|
||
recommended;
|
||
any value lower than 3 enables significantly more efficient attacks.
|
||
.It Fa password
|
||
The password to hash.
|
||
It should be wiped with
|
||
.Xr crypto_wipe 3monocypher
|
||
after being hashed.
|
||
.It Fa password_size
|
||
Length of
|
||
.Fa password ,
|
||
in bytes.
|
||
.It Fa salt
|
||
A password salt.
|
||
This should be filled with random bytes, generated separately for each
|
||
password to be hashed.
|
||
See
|
||
.Xr intro 3monocypher
|
||
for advice about generating random bytes (use the operating system's
|
||
random number generator).
|
||
.It Fa salt_size
|
||
Length of
|
||
.Fa salt ,
|
||
in bytes.
|
||
Must be at least 8.
|
||
16 is recommended.
|
||
.El
|
||
.Pp
|
||
The output hash must not overlap with the work area, or it will be
|
||
wiped along with it.
|
||
Any other overlap is permitted.
|
||
.Pp
|
||
Use
|
||
.Xr crypto_verify16 3monocypher ,
|
||
.Xr crypto_verify32 3monocypher
|
||
or
|
||
.Xr crypto_verify64 3monocypher
|
||
to compare password hashes to prevent timing attacks.
|
||
.Pp
|
||
To select the
|
||
.Fa nb_blocks
|
||
and
|
||
.Fa nb_iterations
|
||
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.
|
||
.Pp
|
||
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
|
||
.Fa nb_blocks
|
||
first.
|
||
If using all available memory is not slow enough, increase
|
||
.Fa nb_iterations .
|
||
.Pp
|
||
.Fn crypto_argon2i_general
|
||
is a variant of
|
||
.Fn crypto_argon2i
|
||
that supports keyed hashing and hashing of additional data.
|
||
The additional arguments are:
|
||
.Bl -tag -width Ds
|
||
.It Fa key
|
||
A key to use in the hash.
|
||
Can be
|
||
.Dv NULL
|
||
if
|
||
.Fa key_size
|
||
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.
|
||
.It Fa key_size
|
||
Length of
|
||
.Fa key ,
|
||
in bytes.
|
||
Must be zero if there is no key.
|
||
.It Fa ad
|
||
Additional data.
|
||
This is additional data that goes into the hash, similar to the
|
||
authenticated encryption with authenticated data (AEAD) construction in
|
||
.Xr crypto_lock_aead 3monocypher .
|
||
This most likely has no practical application but is exposed for the
|
||
sake of completeness.
|
||
This parameter may be
|
||
.Dv NULL
|
||
if
|
||
.Fa ad_size
|
||
is zero.
|
||
.It Fa ad_size
|
||
Length of
|
||
.Fa ad ,
|
||
in bytes.
|
||
Must be zero if there is no additional data.
|
||
.El
|
||
.Sh RETURN VALUES
|
||
These functions return nothing.
|
||
.Sh EXAMPLES
|
||
The following example assumes the existence of
|
||
.Fn arc4random_buf ,
|
||
which fills the given buffer with cryptographically secure random bytes.
|
||
If
|
||
.Fn arc4random_buf
|
||
does not exist on your system, see
|
||
.Xr intro 3monocypher
|
||
for advice about how to generate cryptographically secure random bytes.
|
||
.Pp
|
||
This example shows how to hash a password with the recommended baseline
|
||
parameters:
|
||
.Bd -literal -offset indent
|
||
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);
|
||
}
|
||
.Ed
|
||
.Sh SEE ALSO
|
||
.Xr crypto_lock 3monocypher ,
|
||
.Xr crypto_verify16 3monocypher ,
|
||
.Xr crypto_wipe 3monocypher ,
|
||
.Xr intro 3monocypher
|
||
.Sh STANDARDS
|
||
These functions implement Argon2i.
|
||
An RFC draft is being maintained.
|
||
.Sh HISTORY
|
||
The
|
||
.Fn crypto_argon2i_general
|
||
function first appeared in Monocypher 0.1 but was called
|
||
.Fn crypto_argon2i ;
|
||
it was renamed to its current name in Monocypher 1.1.0.
|
||
The current
|
||
.Fn crypto_argon2i
|
||
first appeared in Monocypher 1.1.0.
|
||
.Sh CAVEATS
|
||
Any deviation from the specified input and output length ranges results
|
||
in
|
||
.Sy undefined behaviour .
|
||
Make sure your inputs are correct.
|