API Reference¶
argon2_cffi
comes with an high-level API and hopefully reasonable defaults for Argon2 parameters that result in a verification time of between 0.5ms and 1ms on recent-ish hardware.
Unless you have any special needs, all you need to know is:
>>> from argon2 import PasswordHasher
>>> ph = PasswordHasher()
>>> hash = ph.hash("s3kr3tp4ssw0rd")
>>> hash
'$argon2i$v=19$m=512,t=2,p=2$5VtWOO3cGWYQHEMaYGbsfQ$AcmqasQgW/wI6wAHAMk4aQ'
>>> ph.verify(hash, "s3kr3tp4ssw0rd")
True
>>> ph.verify(hash, "t0t411ywr0ng")
Traceback (most recent call last):
...
argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
But of course the PasswordHasher
class has all the parametrization you’ll need:
-
class
argon2.
PasswordHasher
(time_cost=2, memory_cost=512, parallelism=2, hash_len=16, salt_len=16, encoding='utf-8')¶ High level class to hash passwords with sensible defaults.
Uses always Argon2i and a random salt.
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()
orverify()
are passed an unicode string, it will be encoded using this encoding.
New in version 16.0.0.
-
hash
(password)¶ Hash password and return an encoded hash.
Parameters: password ( bytes
orunicode
) – Password to hash.Raises: argon2.exceptions.HashingError – If hashing fails. Return type: unicode
-
verify
(hash, password)¶ Verify that password matches hash.
Parameters: - hash (unicode) – An encoded hash as returned from
PasswordHasher.hash()
. - password (
bytes
orunicode
) – The password to verify.
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, raiseVerificationError
otherwise.Return type: Changed in version 16.1.0: Raise
VerifyMismatchError
on mismatches instead of its more generic superclass.- hash (unicode) – An encoded hash as returned from
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
¶
You can see their values in PasswordHasher
.
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
.New 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]
.
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.
-
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.
-
ID
= 2¶ 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.
New 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).
New 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: For an explanation of the Argon2 parameters see
PasswordHasher
.Return type: bytes Raises: argon2.exceptions.HashingError – If hashing fails. New 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, raiseVerificationError
otherwise.Return type: New in version 16.0.0.
Changed in version 16.1.0: Raise
VerifyMismatchError
on mismatches instead of its more generic superclass.- hash (bytes) – An encoded Argon2 hash as returned by
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()
.New 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: Return type: Returns: An Argon2 error code. Can be transformed into a string using
error_to_str()
.New 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:
>>> from argon2.low_level import ARGON2_VERSION, Type, core, ffi, lib
>>> pwd = b"secret"
>>> salt = b"12345678"
>>> hash_len = 8
>>> # Make sure you keep FFI objects alive until *after* the core call!
>>> cout = ffi.new("uint8_t[]", hash_len)
>>> cpwd = ffi.new("uint8_t[]", pwd)
>>> csalt = ffi.new("uint8_t[]", salt)
>>> ctx = ffi.new(
... "argon2_context *", dict(
... version=ARGON2_VERSION,
... out=cout, outlen=hash_len,
... pwd=cpwd, pwdlen=len(pwd),
... salt=csalt, saltlen=len(salt),
... secret=ffi.NULL, secretlen=0,
... ad=ffi.NULL, adlen=0,
... t_cost=1,
... m_cost=8,
... lanes=1, threads=1,
... allocate_cbk=ffi.NULL, free_cbk=ffi.NULL,
... flags=lib.ARGON2_DEFAULT_FLAGS,
... )
... )
>>> ctx
<cdata 'struct Argon2_Context *' owning 120 bytes>
>>> core(ctx, Type.D.value)
0
>>> out = bytes(ffi.buffer(ctx.out, ctx.outlen))
>>> out
b'\xb4\xe2HjO\x14d\x9b'
>>> out == argon2.low_level.hash_secret_raw(pwd, salt, 1, 8, 1, 8, Type.D)
True
All constants and types on argon2.low_level.lib
are guaranteed to stay as long they are not altered by Argon2 itself.
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.
There are no immediate plans to remove them though.
-
argon2.
hash_password
(password, salt=None, time_cost=2, memory_cost=512, parallelism=2, hash_len=16, type=<Type.I: 1>)¶ Legacy alias for
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=2, memory_cost=512, parallelism=2, hash_len=16, type=<Type.I: 1>)¶ Legacy alias for
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: 1>)¶ Legacy alias for
verify_secret()
with default parameters.Deprecated since version 16.0.0: Use
argon2.PasswordHasher
for passwords.