hynek/argon2-cffi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Extract howto

Browse Source
This commit is contained in:
Hynek Schlawack 2023-08-15 08:23:13 +02:00
parent 811841d1b3
commit baead4e9e5
No known key found for this signature in database
GPG Key ID: AE2536227F69F181
4 changed files with 40 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -13,3 +13,4 @@
__pycache__
dist
docs/_build/
Justfile

38
docs/api.rst
View File

@ -3,44 +3,6 @@ API Reference
.. module:: argon2
*argon2-cffi* comes with an high-level API and uses the officially recommended low-memory Argon2 parameters that result in a verification time of 40--50ms on recent-ish hardware.
.. warning::
The current memory requirement is set to rather conservative 64 MB.
However, in memory constrained environments such as Docker containers that can lead to problems.
One possible non-obvious symptom are apparent freezes that are caused by swapping.
Please check :doc:`parameters` for more details.
Unless you have any special needs, all you need to know is:
.. doctest::
>>> from argon2 import PasswordHasher
>>> ph = PasswordHasher()
>>> hash = ph.hash("correct horse battery staple")
>>> hash # doctest: +SKIP
'$argon2id$v=19$m=65536,t=3,p=4$MIIRqgvgQbgj220jfp0MPA$YfwJSVjtjSU0zzV/P3S9nnQ/USre2wvJMjfCIjrTQbg'
>>> ph.verify(hash, "correct horse battery staple")
True
>>> ph.check_needs_rehash(hash)
False
>>> ph.verify(hash, "Tr0ub4dor&3")
Traceback (most recent call last):
...
argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
A login function could thus look like this:
.. literalinclude:: login_example.py
:language: python
----
While the :class:`PasswordHasher` class has the aspiration to be good to use out of the box, it has all the parametrization you'll need:
.. autoclass:: PasswordHasher
:members: from_parameters, hash, verify, check_needs_rehash

38
docs/howto.md Normal file
View File

@ -0,0 +1,38 @@
# How to Hash a Password
*argon2-cffi* comes with an high-level API and uses the officially recommended low-memory Argon2 parameters that result in a verification time of 40--50ms on recent-ish hardware.
:::{warning}
The current memory requirement is set to rather conservative 64 MB.
However, in memory constrained environments such as Docker containers that can lead to problems.
One possible non-obvious symptom are apparent freezes that are caused by swapping.
Please check {doc}`parameters` for more details.
:::
Unless you have any special requirements, all you need to know is:
```python
>>> from argon2 import PasswordHasher
>>> ph = PasswordHasher()
>>> hash = ph.hash("correct horse battery staple")
>>> hash # doctest: +SKIP
'$argon2id$v=19$m=65536,t=3,p=4$MIIRqgvgQbgj220jfp0MPA$YfwJSVjtjSU0zzV/P3S9nnQ/USre2wvJMjfCIjrTQbg'
>>> ph.verify(hash, "correct horse battery staple")
True
>>> ph.check_needs_rehash(hash)
False
>>> ph.verify(hash, "Tr0ub4dor&3")
Traceback (most recent call last):
...
argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
```
A login function could thus look like this:
```{literalinclude} login_example.py
```
---
While the {class}`argon2.PasswordHasher` class has the aspiration to be good to use out of the box, it has all the parametrization you'll need.

1
docs/index.md
View File

@ -15,6 +15,7 @@ Release **{sub-ref}`release`** ([What's new?](https://github.com/hynek/argon2-c
argon2
installation
howto
api
parameters
cli