"Fossies" - the Fresh Open Source Software Archive 
Member "cryptsetup-2.4.3/lib/crypto_backend/argon2/argon2.h" (13 Jan 2022, 16769 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style:
standard) with prefixed line numbers and
code folding option.
Alternatively you can here
view or
download the uninterpreted source code file.
For more information about "argon2.h" see the
Fossies "Dox" file reference documentation.
1 /*
2 * Argon2 reference source code package - reference C implementations
3 *
4 * Copyright 2015
5 * Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, and Samuel Neves
6 *
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:
10 *
11 * - CC0 1.0 Universal : https://creativecommons.org/publicdomain/zero/1.0
12 * - Apache 2.0 : https://www.apache.org/licenses/LICENSE-2.0
13 *
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.
16 */
17
18 #ifndef ARGON2_H
19 #define ARGON2_H
20
21 #include <stdint.h>
22 #include <stddef.h>
23 #include <limits.h>
24
25 #if defined(__cplusplus)
26 extern "C" {
27 #endif
28
29 /* Symbols visibility control */
30 #ifdef A2_VISCTL
31 #define ARGON2_PUBLIC __attribute__((visibility("default")))
32 #define ARGON2_LOCAL __attribute__ ((visibility ("hidden")))
33 #elif _MSC_VER
34 #define ARGON2_PUBLIC __declspec(dllexport)
35 #define ARGON2_LOCAL
36 #else
37 #define ARGON2_PUBLIC
38 #define ARGON2_LOCAL
39 #endif
40
41 /*
42 * Argon2 input parameter restrictions
43 */
44
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)
48
49 /* Minimum and maximum number of threads */
50 #define ARGON2_MIN_THREADS UINT32_C(1)
51 #define ARGON2_MAX_THREADS UINT32_C(0xFFFFFF)
52
53 /* Number of synchronization points between lanes per pass */
54 #define ARGON2_SYNC_POINTS UINT32_C(4)
55
56 /* Minimum and maximum digest size in bytes */
57 #define ARGON2_MIN_OUTLEN UINT32_C(4)
58 #define ARGON2_MAX_OUTLEN UINT32_C(0xFFFFFFFF)
59
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 */
62
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)
69
70 /* Minimum and maximum number of passes */
71 #define ARGON2_MIN_TIME UINT32_C(1)
72 #define ARGON2_MAX_TIME UINT32_C(0xFFFFFFFF)
73
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)
77
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)
81
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)
85
86 /* Minimum and maximum key length in bytes */
87 #define ARGON2_MIN_SECRET UINT32_C(0)
88 #define ARGON2_MAX_SECRET UINT32_C(0xFFFFFFFF)
89
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)
94
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;
98
99 /* Error codes */
100 typedef enum Argon2_ErrorCodes {
101 ARGON2_OK = 0,
102
103 ARGON2_OUTPUT_PTR_NULL = -1,
104
105 ARGON2_OUTPUT_TOO_SHORT = -2,
106 ARGON2_OUTPUT_TOO_LONG = -3,
107
108 ARGON2_PWD_TOO_SHORT = -4,
109 ARGON2_PWD_TOO_LONG = -5,
110
111 ARGON2_SALT_TOO_SHORT = -6,
112 ARGON2_SALT_TOO_LONG = -7,
113
114 ARGON2_AD_TOO_SHORT = -8,
115 ARGON2_AD_TOO_LONG = -9,
116
117 ARGON2_SECRET_TOO_SHORT = -10,
118 ARGON2_SECRET_TOO_LONG = -11,
119
120 ARGON2_TIME_TOO_SMALL = -12,
121 ARGON2_TIME_TOO_LARGE = -13,
122
123 ARGON2_MEMORY_TOO_LITTLE = -14,
124 ARGON2_MEMORY_TOO_MUCH = -15,
125
126 ARGON2_LANES_TOO_FEW = -16,
127 ARGON2_LANES_TOO_MANY = -17,
128
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 */
133
134 ARGON2_MEMORY_ALLOCATION_ERROR = -22,
135
136 ARGON2_FREE_MEMORY_CBK_NULL = -23,
137 ARGON2_ALLOCATE_MEMORY_CBK_NULL = -24,
138
139 ARGON2_INCORRECT_PARAMETER = -25,
140 ARGON2_INCORRECT_TYPE = -26,
141
142 ARGON2_OUT_PTR_MISMATCH = -27,
143
144 ARGON2_THREADS_TOO_FEW = -28,
145 ARGON2_THREADS_TOO_MANY = -29,
146
147 ARGON2_MISSING_ARGS = -30,
148
149 ARGON2_ENCODING_FAIL = -31,
150
151 ARGON2_DECODING_FAIL = -32,
152
153 ARGON2_THREAD_FAIL = -33,
154
155 ARGON2_DECODING_LENGTH_FAIL = -34,
156
157 ARGON2_VERIFY_MISMATCH = -35
158 } argon2_error_codes;
159
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);
163
164 /* Argon2 external data structures */
165
166 /*
167 *****
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
181 *****
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
185 * 4 parallel lanes.
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)
190 */
191 typedef struct Argon2_Context {
192 uint8_t *out; /* output array */
193 uint32_t outlen; /* digest length */
194
195 uint8_t *pwd; /* password array */
196 uint32_t pwdlen; /* password length */
197
198 uint8_t *salt; /* salt array */
199 uint32_t saltlen; /* salt length */
200
201 uint8_t *secret; /* key array */
202 uint32_t secretlen; /* key length */
203
204 uint8_t *ad; /* associated data array */
205 uint32_t adlen; /* associated data length */
206
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 */
211
212 uint32_t version; /* version number */
213
214 allocate_fptr allocate_cbk; /* pointer to memory allocator */
215 deallocate_fptr free_cbk; /* pointer to memory deallocator */
216
217 uint32_t flags; /* array of bool options */
218 } argon2_context;
219
220 /* Argon2 primitive type */
221 typedef enum Argon2_type {
222 Argon2_d = 0,
223 Argon2_i = 1,
224 Argon2_id = 2
225 } argon2_type;
226
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
232 } argon2_version;
233
234 /*
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.
239 */
240 ARGON2_PUBLIC const char *argon2_type2string(argon2_type type, int uppercase);
241
242 /*
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
246 */
247 ARGON2_PUBLIC int argon2_ctx(argon2_context *context, argon2_type type);
248
249 /**
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
263 */
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);
271
272 /**
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
285 */
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);
291
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);
299
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);
305
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);
313
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);
320
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);
329
330 /**
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
336 */
337 ARGON2_PUBLIC int argon2i_verify(const char *encoded, const void *pwd,
338 const size_t pwdlen);
339
340 ARGON2_PUBLIC int argon2d_verify(const char *encoded, const void *pwd,
341 const size_t pwdlen);
342
343 ARGON2_PUBLIC int argon2id_verify(const char *encoded, const void *pwd,
344 const size_t pwdlen);
345
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);
349
350 /**
351 * Argon2d: Version of Argon2 that picks memory blocks depending
352 * on the password and salt. Only for side-channel-free
353 * environment!!
354 *****
355 * @param context Pointer to current Argon2 context
356 * @return Zero if successful, a non zero error code otherwise
357 */
358 ARGON2_PUBLIC int argon2d_ctx(argon2_context *context);
359
360 /**
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.
364 *****
365 * @param context Pointer to current Argon2 context
366 * @return Zero if successful, a non zero error code otherwise
367 */
368 ARGON2_PUBLIC int argon2i_ctx(argon2_context *context);
369
370 /**
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).
375 *****
376 * @param context Pointer to current Argon2 context
377 * @return Zero if successful, a non zero error code otherwise
378 */
379 ARGON2_PUBLIC int argon2id_ctx(argon2_context *context);
380
381 /**
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
387 */
388 ARGON2_PUBLIC int argon2d_verify_ctx(argon2_context *context, const char *hash);
389
390 /**
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
396 */
397 ARGON2_PUBLIC int argon2i_verify_ctx(argon2_context *context, const char *hash);
398
399 /**
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
405 */
406 ARGON2_PUBLIC int argon2id_verify_ctx(argon2_context *context,
407 const char *hash);
408
409 /* generic function underlying the above ones */
410 ARGON2_PUBLIC int argon2_verify_ctx(argon2_context *context, const char *hash,
411 argon2_type type);
412
413 /**
414 * Get the associated error message for given error code
415 * @return The error message associated with the given error code
416 */
417 ARGON2_PUBLIC const char *argon2_error_message(int error_code);
418
419 /**
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
428 */
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);
432
433 #if defined(__cplusplus)
434 }
435 #endif
436
437 #endif