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
u'$argon2i$m=512,t=2,p=2$0FFfEeL6JmUnpxwgwcSC8g$98BmZUa5A/3t5wb3ZxFLBg'
>>> ph.verify(hash, "s3kr3tp4ssw0rd")
True
>>> ph.verify(hash, "t0t411ywr0ng")
Traceback (most recent call last):
...
argon2.exceptions.VerificationError: Decoding failed
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.VerificationError – If verification fails.
Returns: True
on success, raiseVerificationError
otherwise.Return type: - 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
¶ Raised if verification failed.
You can find the original error message from Argon2 in
args[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.
-
-
argon2.low_level.
hash_secret
(secret, salt, time_cost, memory_cost, parallelism, hash_len, type)¶ 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$m=8,t=1,p=1$c29tZXNhbHQ$H0oN1/L3H8t8hcg47pAyJZ8toBh2UbgcMt0zRFrqt4mEJCeKSEWGxt+KpZrMwxvr7M5qktNcc/bk/hvbinueJA'
-
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.VerificationError – If verification fails.
Returns: True
on success, raiseVerificationError
otherwise.Return type: - 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)¶ Hash password and return a raw hash.
This function takes the same parameters as
hash_secret()
.
>>> argon2.low_level.hash_password_raw(b"secret", b"somesalt")
b'\xd8\x87h5X%U<[\xf7\x0e\x18T\x9a\x96\xf3'
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
core
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).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 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(
... 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'j\x9ap\xb4\xe7\xd6\x9c\xcf'
>>> 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.