# API Reference

class argon2.PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4, hash_len=32, salt_len=16, encoding='utf-8', type=Type.ID)

  High level class to hash passwords with sensible defaults.

  Uses Argon2id by default and uses a random salt for hashing. But it can verify any type of Argon2 as long as the hash is correctly encoded.

  The reason for this being a class is both for convenience to carry parameters and to verify the parameters only once. Any unnecessary slowdown when hashing is a tangible advantage for a brute-force attacker.

  Parameters:

    - time_cost (int) – Defines the amount of computation realized and therefore the execution time, given in number of iterations.

    - memory_cost (int) – Defines the memory usage, given in kibibytes.

    - parallelism (int) – Defines the number of parallel threads (changes the resulting hash value).

    - hash_len (int) – Length of the hash in bytes.

    - salt_len (int) – Length of random salt to be generated for each password.

    - encoding (str) – The Argon2 C library expects bytes. So if `hash()` or `verify()` are passed a `str`, it will be encoded using this encoding.

    - type (Type) – Argon2 type to use. Only change for interoperability with legacy systems.

  Added in version 16.0.0.

  Changed in version 18.2.0: Switch from Argon2i to Argon2id based on the recommendation by the current RFC draft. See also Choosing Parameters.

  Changed in version 18.2.0: Changed default memory_cost to 100 MiB and default parallelism to 8.

  Changed in version 18.2.0: `verify` now will determine the type of hash.

  Changed in version 18.3.0: The Argon2 type is configurable now.

  Added in version 21.2.0: `from_parameters()`

  Changed in version 21.2.0: Changed defaults to `argon2.profiles.RFC_9106_LOW_MEMORY`.

  check_needs_rehash(hash)

    Check whether hash was created using the instance’s parameters.

    Whenever your Argon2 parameters – or argon2-cffi’s defaults! – change, you should rehash your passwords at the next opportunity. The common approach is to do that whenever a user logs in, since that should be the only time when you have access to the cleartext password.

    Therefore it’s best practice to check – and if necessary rehash – passwords after each successful authentication.

    Parameters:

      hash (str | bytes) – An encoded Argon2 password hash.

    Returns:

      Whether hash was created using the instance’s parameters.

    Return type:

      bool

    Added in version 18.2.0.

    Changed in version 24.1.0: Accepts bytes for hash.

  classmethod from_parameters(params)

    Construct a `PasswordHasher` from params.

    Returns:

      A `PasswordHasher` instance with the parameters from params.

    Return type:

      PasswordHasher

    Added in version 21.2.0.

  hash(password, *, salt=None)

    Hash password and return an encoded hash.

    Parameters:

      - password (str | bytes) – Password to hash.

      - salt (bytes | None) –

        If None, a random salt is securely created.

        Danger

        You should not pass a salt unless you really know what you are doing.

    Raises:

      argon2.exceptions.HashingError – If hashing fails.

    Returns:

      Hashed password.

    Return type:

      str

    Added in version 23.1.0: salt parameter

  verify(hash, password)

    Verify that password matches hash.

    Warning

    It is assumed that the caller is in full control of the hash. No other parsing than the determination of the hash type is done by argon2-cffi.

    Parameters:

      - hash (str | bytes) – An encoded hash as returned from `PasswordHasher.hash()`.

      - password (str | bytes) – The password to verify.

    Raises:

      - argon2.exceptions.VerifyMismatchError – If verification fails because hash is not valid for password.

      - argon2.exceptions.VerificationError – If verification fails for other reasons.

      - argon2.exceptions.InvalidHashError – If hash is so clearly invalid, that it couldn’t be passed to Argon2.

    Returns:

      `True` on success, otherwise an exception is raised.

    Return type:

      Literal[True]

    Changed in version 16.1.0: Raise `VerifyMismatchError` on mismatches instead of its more generic superclass.

    Added in version 18.2.0: Hash type agility.

If you don’t specify any parameters, the following constants are used:

argon2.DEFAULT_RANDOM_SALT_LENGTH

argon2.DEFAULT_HASH_LENGTH

argon2.DEFAULT_TIME_COST

argon2.DEFAULT_MEMORY_COST

argon2.DEFAULT_PARALLELISM

They are taken from `argon2.profiles.RFC_9106_LOW_MEMORY`, but they may vary depending on the platform. You can use `argon2.profiles.get_default_parameters()` to get the current platform’s defaults.

## Profiles

This module offers access to standardized parameters that you can load using `argon2.PasswordHasher.from_parameters()`. See the source code for concrete values and Choosing Parameters for more information.

Added in version 21.2.0.

You can try them out using the CLI interface. For example:

    $ python -m argon2 --profile RFC_9106_HIGH_MEMORY
    Running Argon2id 100 times with:
    hash_len: 32 bytes
    memory_cost: 2097152 KiB
    parallelism: 4 threads
    time_cost: 1 iterations

    Measuring...

    866.5ms per password verification

That should give you a feeling on how they perform in your environment.

argon2.profiles.RFC_9106_HIGH_MEMORY

  Called “FIRST RECOMMENDED option” by RFC 9106.

  Requires beefy 2 GiB, so be careful in memory-contrained systems.

  Added in version 21.2.0.

argon2.profiles.RFC_9106_LOW_MEMORY

  Called “SECOND RECOMMENDED option” by RFC 9106.

  The main difference is that it only takes 64 MiB of RAM.

  The values from this profile are the default parameters used by `argon2.PasswordHasher`.

  Added in version 21.2.0.

argon2.profiles.PRE_21_2

  The default values that argon2-cffi used from 18.2.0 until 21.2.0.

  Needs 100 MiB of RAM.

  Added in version 21.2.0.

argon2.profiles.CHEAPEST

  This is the cheapest-possible profile.

  Warning

  This is only for testing purposes! Do not use in production!

  Added in version 21.2.0.

argon2.profiles.get_default_parameters()

  Create default parameters for current platform.

  Returns:

    Default, compatible, parameters for current platform.

  Return type:

    Parameters

  Added in version 25.1.0.

## Exceptions

exception argon2.exceptions.VerificationError

  Verification failed.

  You can find the original error message from Argon2 in `args[0]`.

exception argon2.exceptions.VerifyMismatchError

  The secret does not match the hash.

  Subclass of `argon2.exceptions.VerificationError`.

  Added in version 16.1.0.

exception argon2.exceptions.HashingError

  Raised if hashing failed.

  You can find the original error message from Argon2 in `args[0]`.

exception argon2.exceptions.InvalidHashError

  Raised if the hash is invalid before passing it to Argon2.

  Added in version 23.1.0: As a replacement for `argon2.exceptions.InvalidHash`.

argon2.exceptions.InvalidHash

  Deprecated alias for `InvalidHashError`.

  Added in version 18.2.0.

  Deprecated since version 23.1.0: Use `argon2.exceptions.InvalidHashError` instead.

exception argon2.exceptions.UnsupportedParametersError

  Raised if the current platform does not support the parameters.

  For example, in WebAssembly parallelism must be set to 1.

  Added in version 25.1.0.

## Utilities

argon2.extract_parameters(hash)

  Extract parameters from an encoded hash.

  Parameters:

    hash (str) – An encoded Argon2 hash string.

  Returns:

    The parameters used to create the hash.

  Return type:

    Parameters

  Added in version 18.2.0.

class argon2.Parameters(type, version, salt_len, hash_len, time_cost, memory_cost, parallelism)

  Argon2 hash parameters.

  See Choosing Parameters on how to pick them.

  type

    Hash type.

    Type:

      argon2.low_level.Type

  version

    Argon2 version.

    Type:

      int

  salt_len

    Length of the salt in bytes.

    Type:

      int

  hash_len

    Length of the hash in bytes.

    Type:

      int

  time_cost

    Time cost in iterations.

    Type:

      int

  memory_cost

    Memory cost in kibibytes.

    Type:

      int

  parallelism

    Number of parallel threads.

    Type:

      int

  Added in version 18.2.0.

## Low Level

Low-level functions if you want to build your own higher level abstractions.

Warning

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

class argon2.low_level.Type

  Enum of Argon2 variants.

  Please see Choosing Parameters on how to pick one.

  D

    Argon2d is faster and uses data-depending memory access. That makes it less suitable for hashing secrets and more suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.

  I

    Argon2i uses data-independent memory access. Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.

  ID

    Argon2id is a hybrid of Argon2i and Argon2d, using a combination of data-depending and data-independent memory accesses, which gives some of Argon2i’s resistance to side-channel cache timing attacks and much of Argon2d’s resistance to GPU cracking attacks.

    Added in version 16.3.0.

argon2.low_level.ARGON2_VERSION = 19

  The latest version of the Argon2 algorithm that is supported (and used by default).

  Added in version 16.1.0.

argon2.low_level.hash_secret(secret, salt, time_cost, memory_cost, parallelism, hash_len, type, version=19)

  Hash secret and return an encoded hash.

  An encoded hash can be directly passed into `verify_secret()` as it contains all parameters and the salt.

  Parameters:

    - secret (bytes) – Secret to hash.

    - salt (bytes) – A salt. Should be random and different for each secret.

    - type (Type) – Which Argon2 variant to use.

    - version (int) – Which Argon2 version to use.

  For an explanation of the Argon2 parameters see `argon2.PasswordHasher`.

  Returns:

    An encoded Argon2 hash.

  Raises:

    argon2.exceptions.HashingError – If hashing fails.

  Return type:

    bytes

  Added in version 16.0.0.

    >>> import argon2
    >>> argon2.low_level.hash_secret(
    ...     b"secret", b"somesalt",
    ...     time_cost=1, memory_cost=8, parallelism=1, hash_len=64, type=argon2.low_level.Type.D
    ... )
    b'$argon2d$v=19$m=8,t=1,p=1$c29tZXNhbHQ$ba2qC75j0+JAunZZ/L0hZdQgCv+tOieBuKKXSrQiWm7nlkRcK+YqWr0i0m0WABJKelU8qHJp0SZzH0b1Z+ITvQ'

argon2.low_level.verify_secret(hash, secret, type)

  Verify whether secret is correct for hash of type.

  Parameters:

    - hash (bytes) – An encoded Argon2 hash as returned by `hash_secret()`.

    - secret (bytes) – The secret to verify whether it matches the one in hash.

    - type (Type) – Type for hash.

  Raises:

    - argon2.exceptions.VerifyMismatchError – If verification fails because hash is not valid for secret of type.

    - argon2.exceptions.VerificationError – If verification fails for other reasons.

  Returns:

    `True` on success, raise `VerificationError` otherwise.

  Return type:

    Literal[True]

  Added in version 16.0.0.

  Changed in version 16.1.0: Raise `VerifyMismatchError` on mismatches instead of its more generic superclass.

The raw hash can also be computed:

argon2.low_level.hash_secret_raw(secret, salt, time_cost, memory_cost, parallelism, hash_len, type, version=19)

  Hash password and return a raw hash.

  This function takes the same parameters as `hash_secret()`.

  Added in version 16.0.0.

    >>> argon2.low_level.hash_secret_raw(
    ...     b"secret", b"somesalt",
    ...     time_cost=1, memory_cost=8, parallelism=1, hash_len=8, type=argon2.low_level.Type.D
    ... )
    b'\xe4n\xf5\xc8|\xa3>\x1d'

The super low-level `argon2_core()` function is exposed too if you need access to very specific options:

argon2.low_level.core(context, type)

  Direct binding to the `argon2_ctx` function.

  Warning

  This is a strictly advanced function working on raw C data structures. Both Argon2’s and argon2-cffi’s higher-level bindings do a lot of sanity checks and housekeeping work that you are now responsible for (e.g. clearing buffers). The structure of the context object can, has, and will change with any release!

  Use at your own peril; argon2-cffi does not use this binding itself.

  Parameters:

    - context (Any) – A CFFI Argon2 context object (i.e. an `struct Argon2_Context` / `argon2_context`).

    - type (int) – Which Argon2 variant to use. You can use the `value` field of `Type`’s fields.

  Returns:

    An Argon2 error code. Can be transformed into a string using `error_to_str()`.

  Return type:

    int

  Added in version 16.0.0.

In order to use `core()`, you need access to argon2-cffi’s FFI objects. Therefore, it is OK to use `argon2.low_level.ffi` and `argon2.low_level.lib` when working with it. For example, if you wanted to check the RFC 9106 test vectors for Argon2id that include a secret and associated data that both get mixed into the hash and aren’t exposed by the high-level APIs:

    >>> from argon2.low_level import Type, core, ffi, lib

    >>> def low_level_hash(
    ...        password, salt, secret, associated,
    ...        hash_len, version, t_cost, m_cost, lanes, threads):
    ...     cout = ffi.new("uint8_t[]", hash_len)
    ...     cpwd = ffi.new("uint8_t[]", password)
    ...     cad = ffi.new("uint8_t[]", associated)
    ...     csalt = ffi.new("uint8_t[]", salt)
    ...     csecret = ffi.new("uint8_t[]", secret)
    ...
    ...     ctx = ffi.new(
    ...         "argon2_context *",
    ...         {
    ...             "out": cout,
    ...             "outlen": hash_len,
    ...             "version": version,
    ...             "pwd": cpwd,
    ...             "pwdlen": len(cpwd) - 1,
    ...             "salt": csalt,
    ...             "saltlen": len(csalt) - 1,
    ...             "secret": csecret,
    ...             "secretlen": len(csecret) - 1,
    ...             "ad": cad,
    ...             "adlen": len(cad) - 1,
    ...             "t_cost": t_cost,
    ...             "m_cost": m_cost,
    ...             "lanes": lanes,
    ...             "threads": threads,
    ...             "allocate_cbk": ffi.NULL,
    ...             "free_cbk": ffi.NULL,
    ...             "flags": lib.ARGON2_DEFAULT_FLAGS,
    ...         },
    ...     )
    ...
    ...     assert lib.ARGON2_OK == core(ctx, Type.ID.value)
    ...
    ...     return bytes(ffi.buffer(ctx.out, ctx.outlen)).hex()

    >>> password = bytes.fromhex(
    ...    "0101010101010101010101010101010101010101010101010101010101010101"
    ... )
    >>> associated = bytes.fromhex("040404040404040404040404")
    >>> salt = bytes.fromhex("02020202020202020202020202020202")
    >>> secret = bytes.fromhex("0303030303030303")

    >>> assert (
    ...     "0d640df58d78766c08c037a34a8b53c9d01ef0452d75b65eb52520e96b01e659"
    ...     == low_level_hash(
    ...            password, salt, secret, associated,
    ...            32, 19, 3, 32, 4, 4,
    ...     )
    ... )

All constants and types on `argon2.low_level.lib` are guaranteed to stay as long they are not altered by Argon2 itself.

argon2.low_level.error_to_str(error)

  Convert an Argon2 error code into a native string.

  Parameters:

    error (int) – An Argon2 error code as returned by `core()`.

  Returns:

    A human-readable string describing the error.

  Return type:

    str

  Added in version 16.0.0.

## Deprecated APIs

These APIs are from the first release of argon2-cffi and proved to live in an unfortunate mid-level. On one hand they have defaults and check parameters but on the other hand they only consume byte strings.

Therefore the decision has been made to replace them by a high-level (`argon2.PasswordHasher`) and a low-level (`argon2.low_level`) solution. They will be removed in 2024.

argon2.hash_password(password, salt=None, time_cost=3, memory_cost=65536, parallelism=4, hash_len=32, type=Type.I)

  Legacy alias for `argon2.low_level.hash_secret()` with default parameters.

  Deprecated since version 16.0.0: Use `argon2.PasswordHasher` for passwords.

argon2.hash_password_raw(password, salt=None, time_cost=3, memory_cost=65536, parallelism=4, hash_len=32, type=Type.I)

  Legacy alias for `argon2.low_level.hash_secret_raw()` with default parameters.

  Deprecated since version 16.0.0: Use `argon2.PasswordHasher` for passwords.

argon2.verify_password(hash, password, type=Type.I)

  Legacy alias for `argon2.low_level.verify_secret()` with default parameters.

  Deprecated since version 16.0.0: Use `argon2.PasswordHasher` for passwords.