From 9bf4953911b867439ecdcafcb6633787171d3427 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 2 Jun 2023 13:37:17 +0200 Subject: [PATCH] Calm down --- FAQ.md | 4 ++-- README.md | 4 ++-- docs/api.rst | 6 +++--- docs/argon2.rst | 12 ++++++------ docs/cli.rst | 2 +- docs/index.rst | 6 +++--- docs/installation.rst | 14 +++++++------- docs/parameters.rst | 2 +- src/argon2/_password_hasher.py | 12 ++++++------ src/argon2/low_level.py | 10 +++++----- 10 files changed, 36 insertions(+), 36 deletions(-) diff --git a/FAQ.md b/FAQ.md index 71d627c..bcbcb55 100644 --- a/FAQ.md +++ b/FAQ.md @@ -3,7 +3,7 @@ ## I'm using *bcrypt* / *PBKDF2* / *scrypt* / *yescrypt*, do I need to migrate? Using password hashes that aren't memory hard carries a certain risk but there's **no immediate danger or need for action**. -If however you are deciding how to hash password *today*, *Argon2* is the superior, future-proof choice. +If however you are deciding how to hash password *today*, Argon2 is the superior, future-proof choice. But if you already use one of the hashes mentioned in the question, you should be fine for the foreseeable future. If you're using *scrypt* or *yescrypt*, you will be probably fine for good. @@ -11,7 +11,7 @@ If you're using *scrypt* or *yescrypt*, you will be probably fine for good. ## Why do the `verify()` methods raise an Exception instead of returning `False`? -1. The *Argon2* library had no concept of a "wrong password" error in the beginning. +1. The Argon2 library had no concept of a "wrong password" error in the beginning. Therefore when writing these bindings, an exception with the full error had to be raised so you could inspect what went actually wrong. Changing that now would be a very dangerous break of backwards-compatibility. diff --git a/README.md b/README.md index a158ba4..e537563 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# *Argon2* for Python +# Argon2 for Python [![Documentation](https://img.shields.io/badge/Docs-Read%20The%20Docs-black)](https://argon2-cffi.readthedocs.io/) [![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/hynek/argon2-cffi/blob/main/LICENSE) @@ -8,7 +8,7 @@ -[*Argon2*](https://github.com/p-h-c/phc-winner-argon2) won the [Password Hashing Competition](https://www.password-hashing.net/) and *argon2-cffi* is the simplest way to use it in Python and PyPy: +[Argon2](https://github.com/p-h-c/phc-winner-argon2) won the [Password Hashing Competition](https://www.password-hashing.net/) and *argon2-cffi* is the simplest way to use it in Python and PyPy: ```pycon >>> from argon2 import PasswordHasher diff --git a/docs/api.rst b/docs/api.rst index 24a0a9a..cea6593 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,12 +3,12 @@ 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. +*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. + 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. @@ -219,7 +219,7 @@ Therefore it is OK to use ``argon2.low_level.ffi`` and ``argon2.low_level.lib`` >>> 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. +All constants and types on ``argon2.low_level.lib`` are guaranteed to stay as long they are not altered by Argon2 itself. .. autofunction:: error_to_str diff --git a/docs/argon2.rst b/docs/argon2.rst index 81baa82..f9f132c 100644 --- a/docs/argon2.rst +++ b/docs/argon2.rst @@ -1,5 +1,5 @@ -What is *Argon2*? -================= +What is Argon2? +=============== .. note:: @@ -7,14 +7,14 @@ What is *Argon2*? You do **not** need to read or understand anything below this box. -*Argon2* is a secure password hashing algorithm. +Argon2 is a secure password hashing algorithm. It is designed to have both a configurable runtime as well as memory consumption. This means that you can decide how long it takes to hash a password and how much memory is required. -In September 2021, *Argon2* has been standardized by the IETF in :rfc:`9106`. +In September 2021, Argon2 has been standardized by the IETF in :rfc:`9106`. -*Argon2* comes in three variants: Argon2\ **d**, Argon2\ **i**, and Argon2\ **id**. +Argon2 comes in three variants: Argon2\ **d**, Argon2\ **i**, and Argon2\ **id**. Argon2\ **d**'s strength is the resistance against `time–memory trade-offs`_, while Argon2\ **i**'s focus is on resistance against `side-channel attacks`_. Accordingly, Argon2\ **i** was originally considered the correct choice for password hashing and password-based key derivation. @@ -59,7 +59,7 @@ The `Password Hashing Competition`_ took place between 2012 and 2015 to find a n Previously the NIST was in charge but after certain events and revelations_ their integrity has been put into question by the general public. So a group of independent cryptographers and security researchers came together. -In the end, *Argon2* was announced_ as the winner. +In the end, Argon2 was announced_ as the winner. .. _Password Hashing Competition: https://www.password-hashing.net/ .. _revelations: https://en.wikipedia.org/wiki/Dual_EC_DRBG diff --git a/docs/cli.rst b/docs/cli.rst index ddbd446..57be673 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -2,7 +2,7 @@ CLI === To aid you with finding the parameters, *argon2-cffi* offers a CLI interface that can be accessed using ``python -m argon2``. -It will benchmark *Argon2*’s password *verification* in the current environment: +It will benchmark Argon2's password *verification* in the current environment: .. code-block:: console diff --git a/docs/index.rst b/docs/index.rst index afe7f93..65172e4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,6 @@ -================================== -*argon2-cffi*: *Argon2* for Python -================================== +================================ +*argon2-cffi*: Argon2 for Python +================================ Release v\ |release| (:doc:`What's new? `) diff --git a/docs/installation.rst b/docs/installation.rst index c425cfe..75e7861 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,8 +1,8 @@ Installation ============ -Using a Vendored *Argon2* -------------------------- +Using a Vendored Argon2 +----------------------- .. code-block:: bash @@ -10,7 +10,7 @@ Using a Vendored *Argon2* should be all it takes. -But since *argon2-cffi* depends on `argon2-cffi-bindings`_ that vendors *Argon2*'s C code by default, it can lead to complications depending on the platform. +But since *argon2-cffi* depends on `argon2-cffi-bindings`_ that vendors Argon2's C code by default, it can lead to complications depending on the platform. The C code is known to compile and work on all common platforms (including x86, ARM, and PPC). On x86, an SSE2_-optimized version is used. @@ -39,11 +39,11 @@ A working C compiler and `CFFI environment`_ are required to build the `argon2-c If you've been able to compile Python CFFI extensions before, *argon2-cffi* should install without any problems. -Using a System-wide Installation of *Argon2* --------------------------------------------- +Using a System-wide Installation of Argon2 +------------------------------------------ If you set ``ARGON2_CFFI_USE_SYSTEM`` to ``1`` (and *only* ``1``), *argon2-cffi-bindings* will not build its bindings. -However binary wheels are preferred by *pip* and *Argon2* gets installed along with *argon2-cffi* anyway. +However binary wheels are preferred by *pip* and Argon2 gets installed along with *argon2-cffi* anyway. Therefore you also have to instruct *pip* to use a source distribution of `argon2-cffi-bindings`_: @@ -52,7 +52,7 @@ Therefore you also have to instruct *pip* to use a source distribution of `argon env ARGON2_CFFI_USE_SYSTEM=1 \ python -m pip install --no-binary=argon2-cffi-bindings argon2-cffi -This approach can lead to problems around your build chain and you can run into incompatibilities between *Argon2* and *argon2-cffi* if the latter has been tested against a different version. +This approach can lead to problems around your build chain and you can run into incompatibilities between Argon2 and *argon2-cffi* if the latter has been tested against a different version. **It is your own responsibility to deal with these risks if you choose this path.** diff --git a/docs/parameters.rst b/docs/parameters.rst index 09258b7..91ccd68 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -19,7 +19,7 @@ If you need finer tuning, the current recommended best practice is as follow: #. Choose whether you want Argon2i, Argon2d, or Argon2id (``type``). If you don't know what that means, choose Argon2id (:attr:`argon2.Type.ID`). -#. Figure out how many threads can be used on each call to *Argon2* (``parallelism``, called "lanes" in the RFC). +#. Figure out how many threads can be used on each call to Argon2 (``parallelism``, called "lanes" in the RFC). They recommend 4 threads. #. Figure out how much memory each call can afford (``memory_cost``). The APIs use Kibibytes_ (1024 bytes) as base unit. diff --git a/src/argon2/_password_hasher.py b/src/argon2/_password_hasher.py index 24d34a3..9727e89 100644 --- a/src/argon2/_password_hasher.py +++ b/src/argon2/_password_hasher.py @@ -32,7 +32,7 @@ class PasswordHasher: High level class to hash passwords with sensible defaults. Uses Argon2\ **id** by default and always uses a random salt_ for hashing. - But it can verify any type of *Argon2* as long as the hash is correctly + But it can verify any type of Argon2 as long as the hash is correctly encoded. The reason for this being a class is both for convenience to carry @@ -47,10 +47,10 @@ class PasswordHasher: :param int hash_len: Length of the hash in bytes. :param int salt_len: Length of random salt to be generated for each password. - :param str encoding: The *Argon2* C library expects bytes. So if + :param str encoding: The Argon2 C library expects bytes. So if :meth:`hash` or :meth:`verify` are passed a ``str``, it will be encoded using this encoding. - :param Type type: *Argon2* type to use. Only change for interoperability + :param Type type: Argon2 type to use. Only change for interoperability with legacy systems. .. versionadded:: 16.0.0 @@ -60,7 +60,7 @@ class PasswordHasher: .. versionchanged:: 18.2.0 Changed default *memory_cost* to 100 MiB and default *parallelism* to 8. .. versionchanged:: 18.2.0 ``verify`` now will determine the type of hash. - .. versionchanged:: 18.3.0 The *Argon2* type is configurable now. + .. versionchanged:: 18.3.0 The Argon2 type is configurable now. .. versionadded:: 21.2.0 :meth:`from_parameters` .. versionchanged:: 21.2.0 Changed defaults to :data:`argon2.profiles.RFC_9106_LOW_MEMORY`. @@ -194,7 +194,7 @@ class PasswordHasher: :raises argon2.exceptions.VerificationError: If verification fails for other reasons. :raises argon2.exceptions.InvalidHash: If *hash* is so clearly - invalid, that it couldn't be passed to *Argon2*. + invalid, that it couldn't be passed to Argon2. :return: ``True`` on success, raise :exc:`~argon2.exceptions.VerificationError` otherwise. @@ -219,7 +219,7 @@ class PasswordHasher: """ Check whether *hash* was created using the instance's parameters. - Whenever your *Argon2* parameters -- or *argon2-cffi*'s defaults! -- + Whenever your Argon2 parameters -- or *argon2-cffi*'s defaults! -- change, you should rehash your passwords at the next opportunity. The common approach is to do that whenever a user logs in, since that should be the only time when you have access to the cleartext diff --git a/src/argon2/low_level.py b/src/argon2/low_level.py index 5f444f1..1a24214 100644 --- a/src/argon2/low_level.py +++ b/src/argon2/low_level.py @@ -220,7 +220,7 @@ def core(context: Any, type: int) -> int: .. 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 + 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! @@ -228,13 +228,13 @@ def core(context: Any, type: int) -> int: Use at your own peril; *argon2-cffi* does *not* use this binding itself. - :param context: A CFFI *Argon2* context object (i.e. an ``struct - Argon2_Context``/``argon2_context``). - :param int type: Which *Argon2* variant to use. You can use the ``value`` + :param context: A CFFI Argon2 context object (i.e. an ``struct + Argon2_Context`` / ``argon2_context``). + :param int type: Which Argon2 variant to use. You can use the ``value`` field of :class:`Type`'s fields. :rtype: int - :return: An *Argon2* error code. Can be transformed into a string using + :return: An Argon2 error code. Can be transformed into a string using :func:`error_to_str`. .. versionadded:: 16.0.0