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 : http://creativecommons.org/publicdomain/zero/1.0 12 * - Apache 2.0 : http://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 438
Indexes created Tue Feb 24 01:34:59 UTC 2026