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:
>>> 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: - hash (bytes) – An encoded Argon2 password hash as returned by
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.
-