lib/crypto_backend/argon2/argon2.h

   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