1 /* 2 * Argon2 source code package 3 * 4 * Written by Daniel Dinu and Dmitry Khovratovich, 2015 5 * 6 * This work is licensed under a Creative Commons CC0 1.0 License/Waiver. 7 * 8 * You should have received a copy of the CC0 Public Domain Dedication along 9 * with this software. If not, see 10 * <http://creativecommons.org/publicdomain/zero/1.0/>. 11 */ 12 #ifndef argon2_H 13 #define argon2_H 14 15 #include <limits.h> 16 #include <stddef.h> 17 #include <stdint.h> 18 19 /* 20 * Argon2 input parameter restrictions 21 */ 22 23 /* Minimum and maximum number of lanes (degree of parallelism) */ 24 #define ARGON2_MIN_LANES UINT32_C(1) 25 #define ARGON2_MAX_LANES UINT32_C(0xFFFFFF) 26 27 /* Minimum and maximum number of threads */ 28 #define ARGON2_MIN_THREADS UINT32_C(1) 29 #define ARGON2_MAX_THREADS UINT32_C(0xFFFFFF) 30 31 /* Number of synchronization points between lanes per pass */ 32 #define ARGON2_SYNC_POINTS UINT32_C(4) 33 34 /* Minimum and maximum digest size in bytes */ 35 #define ARGON2_MIN_OUTLEN UINT32_C(16) 36 #define ARGON2_MAX_OUTLEN UINT32_C(0xFFFFFFFF) 37 38 /* Minimum and maximum number of memory blocks (each of BLOCK_SIZE bytes) */ 39 #define ARGON2_MIN_MEMORY (2 * ARGON2_SYNC_POINTS) /* 2 blocks per slice */ 40 41 #define ARGON2_MIN(a, b) ((a) < (b) ? (a) : (b)) 42 /* Max memory size is half the addressing space, topping at 2^32 blocks (4 TB) 43 */ 44 #define ARGON2_MAX_MEMORY_BITS \ 45 ARGON2_MIN(UINT32_C(32), (sizeof(void *) * CHAR_BIT - 10 - 1)) 46 #define ARGON2_MAX_MEMORY \ 47 ARGON2_MIN(UINT32_C(0xFFFFFFFF), UINT64_C(1) << ARGON2_MAX_MEMORY_BITS) 48 49 /* Minimum and maximum number of passes */ 50 #define ARGON2_MIN_TIME UINT32_C(1) 51 #define ARGON2_MAX_TIME UINT32_C(0xFFFFFFFF) 52 53 /* Minimum and maximum password length in bytes */ 54 #define ARGON2_MIN_PWD_LENGTH UINT32_C(0) 55 #define ARGON2_MAX_PWD_LENGTH UINT32_C(0xFFFFFFFF) 56 57 /* Minimum and maximum associated data length in bytes */ 58 #define ARGON2_MIN_AD_LENGTH UINT32_C(0) 59 #define ARGON2_MAX_AD_LENGTH UINT32_C(0xFFFFFFFF) 60 61 /* Minimum and maximum salt length in bytes */ 62 #define ARGON2_MIN_SALT_LENGTH UINT32_C(8) 63 #define ARGON2_MAX_SALT_LENGTH UINT32_C(0xFFFFFFFF) 64 65 /* Minimum and maximum key length in bytes */ 66 #define ARGON2_MIN_SECRET UINT32_C(0) 67 #define ARGON2_MAX_SECRET UINT32_C(0xFFFFFFFF) 68 69 #define ARGON2_FLAG_CLEAR_PASSWORD (UINT32_C(1) << 0) 70 #define ARGON2_FLAG_CLEAR_SECRET (UINT32_C(1) << 1) 71 #define ARGON2_FLAG_CLEAR_MEMORY (UINT32_C(1) << 2) 72 #define ARGON2_DEFAULT_FLAGS (UINT32_C(0)) 73 74 /* Error codes */ 75 typedef enum Argon2_ErrorCodes { 76 ARGON2_OK = 0, 77 78 ARGON2_OUTPUT_PTR_NULL = -1, 79 80 ARGON2_OUTPUT_TOO_SHORT = -2, 81 ARGON2_OUTPUT_TOO_LONG = -3, 82 83 ARGON2_PWD_TOO_SHORT = -4, 84 ARGON2_PWD_TOO_LONG = -5, 85 86 ARGON2_SALT_TOO_SHORT = -6, 87 ARGON2_SALT_TOO_LONG = -7, 88 89 ARGON2_AD_TOO_SHORT = -8, 90 ARGON2_AD_TOO_LONG = -9, 91 92 ARGON2_SECRET_TOO_SHORT = -10, 93 ARGON2_SECRET_TOO_LONG = -11, 94 95 ARGON2_TIME_TOO_SMALL = -12, 96 ARGON2_TIME_TOO_LARGE = -13, 97 98 ARGON2_MEMORY_TOO_LITTLE = -14, 99 ARGON2_MEMORY_TOO_MUCH = -15, 100 101 ARGON2_LANES_TOO_FEW = -16, 102 ARGON2_LANES_TOO_MANY = -17, 103 104 ARGON2_PWD_PTR_MISMATCH = -18, /* NULL ptr with non-zero length */ 105 ARGON2_SALT_PTR_MISMATCH = -19, /* NULL ptr with non-zero length */ 106 ARGON2_SECRET_PTR_MISMATCH = -20, /* NULL ptr with non-zero length */ 107 ARGON2_AD_PTR_MISMATCH = -21, /* NULL ptr with non-zero length */ 108 109 ARGON2_MEMORY_ALLOCATION_ERROR = -22, 110 111 ARGON2_FREE_MEMORY_CBK_NULL = -23, 112 ARGON2_ALLOCATE_MEMORY_CBK_NULL = -24, 113 114 ARGON2_INCORRECT_PARAMETER = -25, 115 ARGON2_INCORRECT_TYPE = -26, 116 117 ARGON2_OUT_PTR_MISMATCH = -27, 118 119 ARGON2_THREADS_TOO_FEW = -28, 120 ARGON2_THREADS_TOO_MANY = -29, 121 122 ARGON2_MISSING_ARGS = -30, 123 124 ARGON2_ENCODING_FAIL = -31, 125 126 ARGON2_DECODING_FAIL = -32, 127 128 ARGON2_THREAD_FAIL = -33, 129 130 ARGON2_DECODING_LENGTH_FAIL = -34, 131 132 ARGON2_VERIFY_MISMATCH = -35 133 } argon2_error_codes; 134 135 /* Argon2 external data structures */ 136 137 /* 138 * Context: structure to hold Argon2 inputs: 139 * output array and its length, 140 * password and its length, 141 * salt and its length, 142 * secret and its length, 143 * associated data and its length, 144 * number of passes, amount of used memory (in KBytes, can be rounded up a bit) 145 * number of parallel threads that will be run. 146 * All the parameters above affect the output hash value. 147 * Additionally, two function pointers can be provided to allocate and 148 * deallocate the memory (if NULL, memory will be allocated internally). 149 * Also, three flags indicate whether to erase password, secret as soon as they 150 * are pre-hashed (and thus not needed anymore), and the entire memory 151 ***** 152 * Simplest situation: you have output array out[8], password is stored in 153 * pwd[32], salt is stored in salt[16], you do not have keys nor associated 154 *data. 155 * You need to spend 1 GB of RAM and you run 5 passes of Argon2 with 4 parallel 156 *lanes. 157 * You want to erase the password, but you're OK with last pass not being 158 *erased. 159 * You want to use the default memory allocator. 160 * Then you initialize: 161 * Argon2_Context(out,8,pwd,32,salt,16,NULL,0,NULL,0,5,1<<20,4,4,NULL,NULL,true,false,false,false). 162 */ 163 typedef struct Argon2_Context { 164 uint8_t *out; /* output array */ 165 uint32_t outlen; /* digest length */ 166 167 uint8_t *pwd; /* password array */ 168 uint32_t pwdlen; /* password length */ 169 170 uint8_t *salt; /* salt array */ 171 uint32_t saltlen; /* salt length */ 172 173 uint8_t *secret; /* key array */ 174 uint32_t secretlen; /* key length */ 175 176 uint8_t *ad; /* associated data array */ 177 uint32_t adlen; /* associated data length */ 178 179 uint32_t t_cost; /* number of passes */ 180 uint32_t m_cost; /* amount of memory requested (KB) */ 181 uint32_t lanes; /* number of lanes */ 182 uint32_t threads; /* maximum number of threads */ 183 184 uint32_t flags; /* array of bool options */ 185 } argon2_context; 186 187 /* Argon2 primitive type */ 188 typedef enum Argon2_type { Argon2_i = 1, Argon2_id = 2 } argon2_type; 189 190 /* 191 * Function that performs memory-hard hashing with certain degree of parallelism 192 * @param context Pointer to the Argon2 internal structure 193 * @return Error code if smth is wrong, ARGON2_OK otherwise 194 */ 195 int argon2_ctx(argon2_context *context, argon2_type type); 196 197 /** 198 * Hashes a password with Argon2i, producing an encoded hash 199 * @param t_cost Number of iterations 200 * @param m_cost Sets memory usage to m_cost kibibytes 201 * @param parallelism Number of threads and compute lanes 202 * @param pwd Pointer to password 203 * @param pwdlen Password size in bytes 204 * @param salt Pointer to salt 205 * @param saltlen Salt size in bytes 206 * @param hashlen Desired length of the hash in bytes 207 * @param encoded Buffer where to write the encoded hash 208 * @param encodedlen Size of the buffer (thus max size of the encoded hash) 209 * @pre Different parallelism levels will give different results 210 * @pre Returns ARGON2_OK if successful 211 */ 212 int argon2i_hash_encoded(const uint32_t t_cost, const uint32_t m_cost, 213 const uint32_t parallelism, const void *pwd, 214 const size_t pwdlen, const void *salt, 215 const size_t saltlen, const size_t hashlen, 216 char *encoded, const size_t encodedlen); 217 218 /** 219 * Hashes a password with Argon2id, producing an encoded hash 220 * @param t_cost Number of iterations 221 * @param m_cost Sets memory usage to m_cost kibibytes 222 * @param parallelism Number of threads and compute lanes 223 * @param pwd Pointer to password 224 * @param pwdlen Password size in bytes 225 * @param salt Pointer to salt 226 * @param saltlen Salt size in bytes 227 * @param hashlen Desired length of the hash in bytes 228 * @param encoded Buffer where to write the encoded hash 229 * @param encodedlen Size of the buffer (thus max size of the encoded hash) 230 * @pre Different parallelism levels will give different results 231 * @pre Returns ARGON2_OK if successful 232 */ 233 int argon2id_hash_encoded(const uint32_t t_cost, const uint32_t m_cost, 234 const uint32_t parallelism, const void *pwd, 235 const size_t pwdlen, const void *salt, 236 const size_t saltlen, const size_t hashlen, 237 char *encoded, const size_t encodedlen); 238 239 /** 240 * Hashes a password with Argon2i, producing a raw hash 241 * @param t_cost Number of iterations 242 * @param m_cost Sets memory usage to m_cost kibibytes 243 * @param parallelism Number of threads and compute lanes 244 * @param pwd Pointer to password 245 * @param pwdlen Password size in bytes 246 * @param salt Pointer to salt 247 * @param saltlen Salt size in bytes 248 * @param hash Buffer where to write the raw hash 249 * @param hashlen Desired length of the hash in bytes 250 * @pre Different parallelism levels will give different results 251 * @pre Returns ARGON2_OK if successful 252 */ 253 int argon2i_hash_raw(const uint32_t t_cost, const uint32_t m_cost, 254 const uint32_t parallelism, const void *pwd, 255 const size_t pwdlen, const void *salt, 256 const size_t saltlen, void *hash, const size_t hashlen); 257 258 /** 259 * Hashes a password with Argon2id, producing a raw hash 260 * @param t_cost Number of iterations 261 * @param m_cost Sets memory usage to m_cost kibibytes 262 * @param parallelism Number of threads and compute lanes 263 * @param pwd Pointer to password 264 * @param pwdlen Password size in bytes 265 * @param salt Pointer to salt 266 * @param saltlen Salt size in bytes 267 * @param hash Buffer where to write the raw hash 268 * @param hashlen Desired length of the hash in bytes 269 * @pre Different parallelism levels will give different results 270 * @pre Returns ARGON2_OK if successful 271 */ 272 int argon2id_hash_raw(const uint32_t t_cost, const uint32_t m_cost, 273 const uint32_t parallelism, const void *pwd, 274 const size_t pwdlen, const void *salt, 275 const size_t saltlen, void *hash, const size_t hashlen); 276 277 /* generic function underlying the above ones */ 278 int argon2_hash(const uint32_t t_cost, const uint32_t m_cost, 279 const uint32_t parallelism, const void *pwd, 280 const size_t pwdlen, const void *salt, const size_t saltlen, 281 void *hash, const size_t hashlen, char *encoded, 282 const size_t encodedlen, argon2_type type); 283 284 /** 285 * Verifies a password against an encoded string 286 * Encoded string is restricted as in validate_inputs() 287 * @param encoded String encoding parameters, salt, hash 288 * @param pwd Pointer to password 289 * @pre Returns ARGON2_OK if successful 290 */ 291 int argon2i_verify(const char *encoded, const void *pwd, const size_t pwdlen); 292 293 /** 294 * Verifies a password against an encoded string 295 * Encoded string is restricted as in validate_inputs() 296 * @param encoded String encoding parameters, salt, hash 297 * @param pwd Pointer to password 298 * @pre Returns ARGON2_OK if successful 299 */ 300 int argon2id_verify(const char *encoded, const void *pwd, const size_t pwdlen); 301 302 /* generic function underlying the above ones */ 303 int argon2_verify(const char *encoded, const void *pwd, const size_t pwdlen, 304 argon2_type type); 305 #endif 306