1CRYPTO_ARGON2I(3MONOCYPHER)          LOCAL         CRYPTO_ARGON2I(3MONOCYPHER)
2

NAME

4     crypto_argon2i — password key derivation
5

SYNOPSIS

7     #include <monocypher.h>
8
9     void
10     crypto_argon2i(uint8_t *hash, uint32_t hash_size, void *work_area,
11         uint32_t nb_blocks, uint32_t nb_iterations, const uint8_t *password,
12         uint32_t password_size, const uint8_t *salt, uint32_t salt_size);
13
14     void
15     crypto_argon2i_general(uint8_t *hash, uint32_t hash_size,
16         void *work_area, uint32_t nb_blocks, uint32_t nb_iterations,
17         const uint8_t *password, uint32_t password_size, const uint8_t *salt,
18         uint32_t salt_size, const uint8_t *key, uint32_t key_size,
19         const uint8_t *ad, uint32_t ad_size);
20

DESCRIPTION

22     Argon2i is a resource intensive password key derivation scheme optimised
23     for the typical x86-like processor.  It runs in constant time with re‐
24     spect to the contents of the password.
25
26     Typical applications are password checking (for online services), and key
27     derivation (for encryption).  Derived keys can be used to encrypt, for
28     example, private keys or password databases.
29
30     The version provided by Monocypher has no threading support, so the de‐
31     gree of parallelism is limited to 1.  This is considered good enough for
32     most purposes.
33
34     The arguments to crypto_argon2i() are:
35
36     hash    The output hash.  If all parameters to crypto_argon2i() or
37             crypto_argon2i_general() are identical between two calls, then
38             the output hash is also identical.  In other words, all input pa‐
39             rameters passed to the function influence the output value.
40
41     hash_size
42             Length of hash, in bytes.  This argument should be set to 32 or
43             64 for compatibility with the crypto_verify*() constant time com‐
44             parison functions.
45
46     work_area
47             Temporary buffer for the algorithm, allocated by the caller.  It
48             must be nb_blocks × 1024 bytes big, and suitably aligned for
49             64-bit integers.  If you are not sure how to allocate that buf‐
50             fer, just use malloc().
51
52             The work area is automatically wiped by crypto_argon2i().
53
54     nb_blocks
55             The number of blocks for the work area.  Must be at least 8.  A
56             value of 100000 (one hundred megabytes) is a good starting point.
57             If the computation takes too long, reduce this number.  If it is
58             too fast, increase this number.  If it is still too fast with all
59             available memory, increase nb_iterations.
60
61     nb_iterations
62             The number of iterations.  It must be at least 1.  A value of 3
63             is strongly recommended; any value lower than 3 enables signifi‐
64             cantly more efficient attacks.
65
66     password
67             The password to hash.  It should be wiped with
68             crypto_wipe(3monocypher) after being hashed.
69
70     password_size
71             Length of password, in bytes.
72
73     salt    A password salt.  This should be filled with random bytes, gener‐
74             ated separately for each password to be hashed.  See
75             intro(3monocypher) for advice about generating random bytes (use
76             the operating system's random number generator).
77
78     salt_size
79             Length of salt, in bytes.  Must be at least 8.  16 is recom‐
80             mended.
81
82     The arguments may overlap or point at the same buffer.
83
84     Use crypto_verify16(3monocypher), crypto_verify32(3monocypher) or
85     crypto_verify64(3monocypher) to compare password hashes to prevent timing
86     attacks.
87
88     To select the nb_blocks and nb_iterations parameters, it should first be
89     decided how long the computation should take.  For user authentication,
90     values somewhere between half a second (convenient) and several seconds
91     (paranoid) are recommended.  The computation should use as much memory as
92     can be spared.
93
94     Since parameter selection depends on your hardware, some trial and error
95     will be required in order to determine the ideal settings.  Three itera‐
96     tions and 100000 blocks (that is, one hundred megabytes of memory) is a
97     good starting point.  Adjust nb_blocks first.  If using all available
98     memory is not slow enough, increase nb_iterations.
99
100     crypto_argon2i_general() is a variant of crypto_argon2i() that supports
101     keyed hashing and hashing of additional data.  The additional arguments
102     are:
103
104     key     A key to use in the hash.  Can be NULL if key_size is zero.  The
105             key is generally not needed, but it does have some uses.  In the
106             context of password derivation, it would be stored separately
107             from the password database, and would remain secret even if an
108             attacker were to steal the database.  Note that changing the key
109             requires rehashing the user's password, which is only possible
110             upon user login.
111
112     key_size
113             Length of key, in bytes.  Must be zero if there is no key.
114
115     ad      Additional data.  This is additional data that goes into the
116             hash, similar to the authenticated encryption with authenticated
117             data (AEAD) construction in crypto_lock_aead(3monocypher).  This
118             most likely has no practical application but is exposed for the
119             sake of completeness.  This parameter may be NULL if ad_size is
120             zero.
121
122     ad_size
123             Length of ad, in bytes.  Must be zero if there is no additional
124             data.
125

RETURN VALUES

127     These functions return nothing.
128

EXAMPLES

130     The following example assumes the existence of arc4random_buf(), which
131     fills the given buffer with cryptographically secure random bytes.  If
132     arc4random_buf() does not exist on your system, see intro(3monocypher)
133     for advice about how to generate cryptographically secure random bytes.
134
135     This example shows how to hash a password with the recommended baseline
136     parameters:
137
138           uint8_t        hash[32];                    /* Output hash     */
139           char          *password = "Okay Password!"; /* User's password */
140           uint32_t       password_size = 14;          /* Password length */
141           uint8_t        salt[16];                    /* Random salt     */
142           const uint32_t nb_blocks = 100000;          /* 100 megabytes   */
143           const uint32_t nb_iterations = 3;           /* 3 iterations    */
144           void *work_area = malloc(nb_blocks * 1024); /* Work area       */
145           if (work_area == NULL) {
146               /* Handle malloc() failure */
147               /* Wipe secrets if they are no longer needed */
148               crypto_wipe(password, password_size);
149           } else {
150               arc4random_buf(salt, 16);
151               crypto_argon2i(hash, 32,
152                              work_area, nb_blocks, nb_iterations,
153                              (uint8_t *)password, password_size,
154                              salt, 16);
155               /* Wipe secrets if they are no longer needed */
156               crypto_wipe(password, password_size);
157               free(work_area);
158           }
159

SEE ALSO

161     crypto_lock(3monocypher), crypto_verify16(3monocypher),
162     crypto_wipe(3monocypher), intro(3monocypher)
163

STANDARDS

165     These functions implement Argon2i.  An RFC draft is being maintained.
166

HISTORY

168     The crypto_argon2i_general() function first appeared in Monocypher 0.1
169     but was called crypto_argon2i(); it was renamed to its current name in
170     Monocypher 1.1.0.  The current crypto_argon2i() first appeared in Mono‐
171     cypher 1.1.0.
172

CAVEATS

174     Any deviation from the specified input and output length ranges results
175     in undefined behaviour.  Make sure your inputs are correct.
176
177BSD                           September 26, 2020                           BSD
Impressum