API Reference

argon2_cffi comes with hopefully reasonable defaults for Argon2 parameters that result in a verification time of between 0.5ms and 1ms on recent-ish hardware.

So unless you have any special needs, all you need to know is:

>>> import argon2
>>> hash = argon2.hash_password(b"s3kr3tp4ssw0rd")
>>> hash  
b'$argon2i$m=512,t=2,p=2$0FFfEeL6JmUnpxwgwcSC8g$98BmZUa5A/3t5wb3ZxFLBg'
>>> argon2.verify_password(hash, b"s3kr3tp4ssw0rd")
True
>>> argon2.verify_password(hash, b"t0t411ywr0ng")
Traceback (most recent call last):
  ...
argon2.exceptions.VerificationError: Decoding failed

But of course, argon2_cffi gives you more control should you need it:

argon2.hash_password(password, salt=None, time_cost=2, memory_cost=512, parallelism=2, hash_len=16, type=<Type.I: 1>)

Hash password and return an encoded hash.

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

Parameters:
  • password (bytes) – Password to hash.
  • salt (bytes) – A salt. Should be random and different for each password. Will generate a random salt for you if left None (recommended).
  • 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.
  • type (Type) – Which Argon2 variant to use. In doubt use the default Type.I which is better suited for passwords.
Return type:

bytes

 
>>> argon2.hash_password(
...     b"secret", b"somesalt",
...     time_cost=1,         # number of iterations
...     memory_cost=8,       # used memory in KiB
...     parallelism=1,       # number of threads used; changes hash!
...     hash_len=64,         # length of resulting raw hash
...     type=argon2.Type.D,  # choose Argon2i or Argon2d
... )
b'$argon2d$m=8,t=1,p=1$c29tZXNhbHQ$H0oN1/L3H8t8hcg47pAyJZ8toBh2UbgcMt0zRFrqt4mEJCeKSEWGxt+KpZrMwxvr7M5qktNcc/bk/hvbinueJA'
argon2.verify_password(hash, password, type=<Type.I: 1>)

Verify whether password is correct for hash of type.

Parameters:
  • hash (bytes) – An encoded Argon2 password hash as returned by hash_password().
  • password (bytes) – The password to verify whether it matches the one in hash.
  • type (Type) – Type for hash.
Returns:

True on success, throw exception otherwise.
Return type:

bool

The raw hash can also be computed:

argon2.hash_password_raw(password, salt=None, time_cost=2, memory_cost=512, parallelism=2, hash_len=16, type=<Type.I: 1>)

Hash password and return a raw hash.

This function takes the same parameters as hash_password().

>>> argon2.hash_password_raw(b"secret", b"somesalt")
b'\xd8\x87h5X%U<[\xf7\x0e\x18T\x9a\x96\xf3'
class argon2.Type

Enum of Argon2 variants.

D = 0

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

I = 1

Argon2i uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.