"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