2 * Argon2 reference source code package - reference C implementations
5 * Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, and Samuel Neves
7 * You may use this work under the terms of a Creative Commons CC0 1.0
8 * License/Waiver or the Apache Public License 2.0, at your option. The terms of
9 * these licenses can be found at:
11 * - CC0 1.0 Universal : https://creativecommons.org/publicdomain/zero/1.0
12 * - Apache 2.0 : https://www.apache.org/licenses/LICENSE-2.0
14 * You should have received a copy of both of these licenses along with this
15 * software. If not, they may be obtained at the above URLs.
25 #if defined(__cplusplus)
29 /* Symbols visibility control */
31 #define ARGON2_PUBLIC __attribute__((visibility("default")))
32 #define ARGON2_LOCAL __attribute__ ((visibility ("hidden")))
34 #define ARGON2_PUBLIC __declspec(dllexport)
42 * Argon2 input parameter restrictions
45 /* Minimum and maximum number of lanes (degree of parallelism) */
46 #define ARGON2_MIN_LANES UINT32_C(1)
47 #define ARGON2_MAX_LANES UINT32_C(0xFFFFFF)
49 /* Minimum and maximum number of threads */
50 #define ARGON2_MIN_THREADS UINT32_C(1)
51 #define ARGON2_MAX_THREADS UINT32_C(0xFFFFFF)
53 /* Number of synchronization points between lanes per pass */
54 #define ARGON2_SYNC_POINTS UINT32_C(4)
56 /* Minimum and maximum digest size in bytes */
57 #define ARGON2_MIN_OUTLEN UINT32_C(4)
58 #define ARGON2_MAX_OUTLEN UINT32_C(0xFFFFFFFF)
60 /* Minimum and maximum number of memory blocks (each of BLOCK_SIZE bytes) */
61 #define ARGON2_MIN_MEMORY (2 * ARGON2_SYNC_POINTS) /* 2 blocks per slice */
63 #define ARGON2_MIN(a, b) ((a) < (b) ? (a) : (b))
64 /* Max memory size is addressing-space/2, topping at 2^32 blocks (4 TB) */
65 #define ARGON2_MAX_MEMORY_BITS \
66 ARGON2_MIN(UINT32_C(32), (sizeof(void *) * CHAR_BIT - 10 - 1))
67 #define ARGON2_MAX_MEMORY \
68 ARGON2_MIN(UINT32_C(0xFFFFFFFF), UINT64_C(1) << ARGON2_MAX_MEMORY_BITS)
70 /* Minimum and maximum number of passes */
71 #define ARGON2_MIN_TIME UINT32_C(1)
72 #define ARGON2_MAX_TIME UINT32_C(0xFFFFFFFF)
74 /* Minimum and maximum password length in bytes */
75 #define ARGON2_MIN_PWD_LENGTH UINT32_C(0)
76 #define ARGON2_MAX_PWD_LENGTH UINT32_C(0xFFFFFFFF)
78 /* Minimum and maximum associated data length in bytes */
79 #define ARGON2_MIN_AD_LENGTH UINT32_C(0)
80 #define ARGON2_MAX_AD_LENGTH UINT32_C(0xFFFFFFFF)
82 /* Minimum and maximum salt length in bytes */
83 #define ARGON2_MIN_SALT_LENGTH UINT32_C(8)
84 #define ARGON2_MAX_SALT_LENGTH UINT32_C(0xFFFFFFFF)
86 /* Minimum and maximum key length in bytes */
87 #define ARGON2_MIN_SECRET UINT32_C(0)
88 #define ARGON2_MAX_SECRET UINT32_C(0xFFFFFFFF)
90 /* Flags to determine which fields are securely wiped (default = no wipe). */
91 #define ARGON2_DEFAULT_FLAGS UINT32_C(0)
92 #define ARGON2_FLAG_CLEAR_PASSWORD (UINT32_C(1) << 0)
93 #define ARGON2_FLAG_CLEAR_SECRET (UINT32_C(1) << 1)
95 /* Global flag to determine if we are wiping internal memory buffers. This flag
96 * is defined in core.c and defaults to 1 (wipe internal memory). */
97 extern int FLAG_clear_internal_memory;
100 typedef enum Argon2_ErrorCodes {
103 ARGON2_OUTPUT_PTR_NULL = -1,
105 ARGON2_OUTPUT_TOO_SHORT = -2,
106 ARGON2_OUTPUT_TOO_LONG = -3,
108 ARGON2_PWD_TOO_SHORT = -4,
109 ARGON2_PWD_TOO_LONG = -5,
111 ARGON2_SALT_TOO_SHORT = -6,
112 ARGON2_SALT_TOO_LONG = -7,
114 ARGON2_AD_TOO_SHORT = -8,
115 ARGON2_AD_TOO_LONG = -9,
117 ARGON2_SECRET_TOO_SHORT = -10,
118 ARGON2_SECRET_TOO_LONG = -11,
120 ARGON2_TIME_TOO_SMALL = -12,
121 ARGON2_TIME_TOO_LARGE = -13,
123 ARGON2_MEMORY_TOO_LITTLE = -14,
124 ARGON2_MEMORY_TOO_MUCH = -15,
126 ARGON2_LANES_TOO_FEW = -16,
127 ARGON2_LANES_TOO_MANY = -17,
129 ARGON2_PWD_PTR_MISMATCH = -18, /* NULL ptr with non-zero length */
130 ARGON2_SALT_PTR_MISMATCH = -19, /* NULL ptr with non-zero length */
131 ARGON2_SECRET_PTR_MISMATCH = -20, /* NULL ptr with non-zero length */
132 ARGON2_AD_PTR_MISMATCH = -21, /* NULL ptr with non-zero length */
134 ARGON2_MEMORY_ALLOCATION_ERROR = -22,
136 ARGON2_FREE_MEMORY_CBK_NULL = -23,
137 ARGON2_ALLOCATE_MEMORY_CBK_NULL = -24,
139 ARGON2_INCORRECT_PARAMETER = -25,
140 ARGON2_INCORRECT_TYPE = -26,
142 ARGON2_OUT_PTR_MISMATCH = -27,
144 ARGON2_THREADS_TOO_FEW = -28,
145 ARGON2_THREADS_TOO_MANY = -29,
147 ARGON2_MISSING_ARGS = -30,
149 ARGON2_ENCODING_FAIL = -31,
151 ARGON2_DECODING_FAIL = -32,
153 ARGON2_THREAD_FAIL = -33,
155 ARGON2_DECODING_LENGTH_FAIL = -34,
157 ARGON2_VERIFY_MISMATCH = -35
158 } argon2_error_codes;
160 /* Memory allocator types --- for external allocation */
161 typedef int (*allocate_fptr)(uint8_t **memory, size_t bytes_to_allocate);
162 typedef void (*deallocate_fptr)(uint8_t *memory, size_t bytes_to_allocate);
164 /* Argon2 external data structures */
168 * Context: structure to hold Argon2 inputs:
169 * output array and its length,
170 * password and its length,
171 * salt and its length,
172 * secret and its length,
173 * associated data and its length,
174 * number of passes, amount of used memory (in KBytes, can be rounded up a bit)
175 * number of parallel threads that will be run.
176 * All the parameters above affect the output hash value.
177 * Additionally, two function pointers can be provided to allocate and
178 * deallocate the memory (if NULL, memory will be allocated internally).
179 * Also, three flags indicate whether to erase password, secret as soon as they
180 * are pre-hashed (and thus not needed anymore), and the entire memory
182 * Simplest situation: you have output array out[8], password is stored in
183 * pwd[32], salt is stored in salt[16], you do not have keys nor associated
184 * data. You need to spend 1 GB of RAM and you run 5 passes of Argon2d with
186 * You want to erase the password, but you're OK with last pass not being
187 * erased. You want to use the default memory allocator.
188 * Then you initialize:
189 Argon2_Context(out,8,pwd,32,salt,16,NULL,0,NULL,0,5,1<<20,4,4,NULL,NULL,true,false,false,false)
191 typedef struct Argon2_Context {
192 uint8_t *out; /* output array */
193 uint32_t outlen; /* digest length */
195 uint8_t *pwd; /* password array */
196 uint32_t pwdlen; /* password length */
198 uint8_t *salt; /* salt array */
199 uint32_t saltlen; /* salt length */
201 uint8_t *secret; /* key array */
202 uint32_t secretlen; /* key length */
204 uint8_t *ad; /* associated data array */
205 uint32_t adlen; /* associated data length */
207 uint32_t t_cost; /* number of passes */
208 uint32_t m_cost; /* amount of memory requested (KB) */
209 uint32_t lanes; /* number of lanes */
210 uint32_t threads; /* maximum number of threads */
212 uint32_t version; /* version number */
214 allocate_fptr allocate_cbk; /* pointer to memory allocator */
215 deallocate_fptr free_cbk; /* pointer to memory deallocator */
217 uint32_t flags; /* array of bool options */
220 /* Argon2 primitive type */
221 typedef enum Argon2_type {
227 /* Version of the algorithm */
228 typedef enum Argon2_version {
229 ARGON2_VERSION_10 = 0x10,
230 ARGON2_VERSION_13 = 0x13,
231 ARGON2_VERSION_NUMBER = ARGON2_VERSION_13
235 * Function that gives the string representation of an argon2_type.
236 * @param type The argon2_type that we want the string for
237 * @param uppercase Whether the string should have the first letter uppercase
238 * @return NULL if invalid type, otherwise the string representation.
240 ARGON2_PUBLIC const char *argon2_type2string(argon2_type type, int uppercase);
243 * Function that performs memory-hard hashing with certain degree of parallelism
244 * @param context Pointer to the Argon2 internal structure
245 * @return Error code if smth is wrong, ARGON2_OK otherwise
247 ARGON2_PUBLIC int argon2_ctx(argon2_context *context, argon2_type type);
250 * Hashes a password with Argon2i, producing an encoded hash
251 * @param t_cost Number of iterations
252 * @param m_cost Sets memory usage to m_cost kibibytes
253 * @param parallelism Number of threads and compute lanes
254 * @param pwd Pointer to password
255 * @param pwdlen Password size in bytes
256 * @param salt Pointer to salt
257 * @param saltlen Salt size in bytes
258 * @param hashlen Desired length of the hash in bytes
259 * @param encoded Buffer where to write the encoded hash
260 * @param encodedlen Size of the buffer (thus max size of the encoded hash)
261 * @pre Different parallelism levels will give different results
262 * @pre Returns ARGON2_OK if successful
264 ARGON2_PUBLIC int argon2i_hash_encoded(const uint32_t t_cost,
265 const uint32_t m_cost,
266 const uint32_t parallelism,
267 const void *pwd, const size_t pwdlen,
268 const void *salt, const size_t saltlen,
269 const size_t hashlen, char *encoded,
270 const size_t encodedlen);
273 * Hashes a password with Argon2i, producing a raw hash at @hash
274 * @param t_cost Number of iterations
275 * @param m_cost Sets memory usage to m_cost kibibytes
276 * @param parallelism Number of threads and compute lanes
277 * @param pwd Pointer to password
278 * @param pwdlen Password size in bytes
279 * @param salt Pointer to salt
280 * @param saltlen Salt size in bytes
281 * @param hash Buffer where to write the raw hash - updated by the function
282 * @param hashlen Desired length of the hash in bytes
283 * @pre Different parallelism levels will give different results
284 * @pre Returns ARGON2_OK if successful
286 ARGON2_PUBLIC int argon2i_hash_raw(const uint32_t t_cost, const uint32_t m_cost,
287 const uint32_t parallelism, const void *pwd,
288 const size_t pwdlen, const void *salt,
289 const size_t saltlen, void *hash,
290 const size_t hashlen);
292 ARGON2_PUBLIC int argon2d_hash_encoded(const uint32_t t_cost,
293 const uint32_t m_cost,
294 const uint32_t parallelism,
295 const void *pwd, const size_t pwdlen,
296 const void *salt, const size_t saltlen,
297 const size_t hashlen, char *encoded,
298 const size_t encodedlen);
300 ARGON2_PUBLIC int argon2d_hash_raw(const uint32_t t_cost, const uint32_t m_cost,
301 const uint32_t parallelism, const void *pwd,
302 const size_t pwdlen, const void *salt,
303 const size_t saltlen, void *hash,
304 const size_t hashlen);
306 ARGON2_PUBLIC int argon2id_hash_encoded(const uint32_t t_cost,
307 const uint32_t m_cost,
308 const uint32_t parallelism,
309 const void *pwd, const size_t pwdlen,
310 const void *salt, const size_t saltlen,
311 const size_t hashlen, char *encoded,
312 const size_t encodedlen);
314 ARGON2_PUBLIC int argon2id_hash_raw(const uint32_t t_cost,
315 const uint32_t m_cost,
316 const uint32_t parallelism, const void *pwd,
317 const size_t pwdlen, const void *salt,
318 const size_t saltlen, void *hash,
319 const size_t hashlen);
321 /* generic function underlying the above ones */
322 ARGON2_PUBLIC int argon2_hash(const uint32_t t_cost, const uint32_t m_cost,
323 const uint32_t parallelism, const void *pwd,
324 const size_t pwdlen, const void *salt,
325 const size_t saltlen, void *hash,
326 const size_t hashlen, char *encoded,
327 const size_t encodedlen, argon2_type type,
328 const uint32_t version);
331 * Verifies a password against an encoded string
332 * Encoded string is restricted as in validate_inputs()
333 * @param encoded String encoding parameters, salt, hash
334 * @param pwd Pointer to password
335 * @pre Returns ARGON2_OK if successful
337 ARGON2_PUBLIC int argon2i_verify(const char *encoded, const void *pwd,
338 const size_t pwdlen);
340 ARGON2_PUBLIC int argon2d_verify(const char *encoded, const void *pwd,
341 const size_t pwdlen);
343 ARGON2_PUBLIC int argon2id_verify(const char *encoded, const void *pwd,
344 const size_t pwdlen);
346 /* generic function underlying the above ones */
347 ARGON2_PUBLIC int argon2_verify(const char *encoded, const void *pwd,
348 const size_t pwdlen, argon2_type type);
351 * Argon2d: Version of Argon2 that picks memory blocks depending
352 * on the password and salt. Only for side-channel-free
355 * @param context Pointer to current Argon2 context
356 * @return Zero if successful, a non zero error code otherwise
358 ARGON2_PUBLIC int argon2d_ctx(argon2_context *context);
361 * Argon2i: Version of Argon2 that picks memory blocks
362 * independent on the password and salt. Good for side-channels,
363 * but worse w.r.t. tradeoff attacks if only one pass is used.
365 * @param context Pointer to current Argon2 context
366 * @return Zero if successful, a non zero error code otherwise
368 ARGON2_PUBLIC int argon2i_ctx(argon2_context *context);
371 * Argon2id: Version of Argon2 where the first half-pass over memory is
372 * password-independent, the rest are password-dependent (on the password and
373 * salt). OK against side channels (they reduce to 1/2-pass Argon2i), and
374 * better with w.r.t. tradeoff attacks (similar to Argon2d).
376 * @param context Pointer to current Argon2 context
377 * @return Zero if successful, a non zero error code otherwise
379 ARGON2_PUBLIC int argon2id_ctx(argon2_context *context);
382 * Verify if a given password is correct for Argon2d hashing
383 * @param context Pointer to current Argon2 context
384 * @param hash The password hash to verify. The length of the hash is
385 * specified by the context outlen member
386 * @return Zero if successful, a non zero error code otherwise
388 ARGON2_PUBLIC int argon2d_verify_ctx(argon2_context *context, const char *hash);
391 * Verify if a given password is correct for Argon2i hashing
392 * @param context Pointer to current Argon2 context
393 * @param hash The password hash to verify. The length of the hash is
394 * specified by the context outlen member
395 * @return Zero if successful, a non zero error code otherwise
397 ARGON2_PUBLIC int argon2i_verify_ctx(argon2_context *context, const char *hash);
400 * Verify if a given password is correct for Argon2id hashing
401 * @param context Pointer to current Argon2 context
402 * @param hash The password hash to verify. The length of the hash is
403 * specified by the context outlen member
404 * @return Zero if successful, a non zero error code otherwise
406 ARGON2_PUBLIC int argon2id_verify_ctx(argon2_context *context,
409 /* generic function underlying the above ones */
410 ARGON2_PUBLIC int argon2_verify_ctx(argon2_context *context, const char *hash,
414 * Get the associated error message for given error code
415 * @return The error message associated with the given error code
417 ARGON2_PUBLIC const char *argon2_error_message(int error_code);
420 * Returns the encoded hash length for the given input parameters
421 * @param t_cost Number of iterations
422 * @param m_cost Memory usage in kibibytes
423 * @param parallelism Number of threads; used to compute lanes
424 * @param saltlen Salt size in bytes
425 * @param hashlen Hash size in bytes
426 * @param type The argon2_type that we want the encoded length for
427 * @return The encoded hash length in bytes
429 ARGON2_PUBLIC size_t argon2_encodedlen(uint32_t t_cost, uint32_t m_cost,
430 uint32_t parallelism, uint32_t saltlen,
431 uint32_t hashlen, argon2_type type);
433 #if defined(__cplusplus)