MyST

docs/argon2.md

@@ -0,0 +1,61 @@
+# What is Argon2?
+
+:::{note}
+**TL;DR**: Use {class}`argon2.PasswordHasher` with its default parameters to securely hash your passwords.
+
+You do **not** need to read or understand anything below this box.
+:::
+
+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`.
+
+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.
+In practice it turned out that a *combination* of d and i -- that combines their strenghts -- is the better choice.
+And so Argon2**id** was born and is now considered the *main variant* (and the only variant required by the RFC to be implemented).
+
+
+## Why “just use bcrypt” Is Not the Best Answer (Anymore)
+
+The current workhorses of password hashing are unquestionably [*bcrypt*] and [PBKDF2].
+And while they're still fine to use, the password cracking community embraced new technologies like [GPU]s and [ASIC]s to crack password in a highly parallel fashion.
+
+An effective measure against extreme parallelism proved making computation of password hashes also *memory* hard.
+The best known implementation of that approach is to date [*scrypt*].
+However according to the [Argon2 paper] [^outdated], page 2:
+
+> \[…\] the existence of a trivial time-memory tradeoff allows compact implementations with the same energy cost.
+
+Therefore a new algorithm was needed.
+This time future-proof and with committee-vetting instead of single implementors.
+
+[^outdated]: Please note that the paper is in some parts outdated.
+    For instance it predates the genesis of Argon2**id**.
+    Generally please refer to {rfc}`9106` instead.
+
+
+## Password Hashing Competition
+
+The [Password Hashing Competition] took place between 2012 and 2015 to find a new, secure, and future-proof password hashing algorithm.
+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.
+
+[announced]: https://groups.google.com/forum/#!topic/crypto-competitions/3QNdmwBS98o
+[argon2 paper]: https://www.password-hashing.net/argon2-specs.pdf
+[asic]: https://en.wikipedia.org/wiki/Application-specific_integrated_circuit
+[*bcrypt*]: https://en.wikipedia.org/wiki/Bcrypt
+[gpu]: https://hashcat.net/hashcat/
+[password hashing competition]: https://www.password-hashing.net/
+[pbkdf2]: https://en.wikipedia.org/wiki/PBKDF2
+[revelations]: https://en.wikipedia.org/wiki/Dual_EC_DRBG
+[*scrypt*]: https://en.wikipedia.org/wiki/Scrypt
+[side-channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack
+[time–memory trade-offs]: https://en.wikipedia.org/wiki/Space–time_tradeoff

docs/cli.md

@@ -0,0 +1,24 @@
+# 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:
+
+```console
+$ python -m argon2
+Running Argon2id 100 times with:
+hash_len: 32 bytes
+memory_cost: 65536 KiB
+parallelism: 4 threads
+time_cost: 3 iterations
+
+Measuring...
+
+45.7ms per password verification
+```
+
+You can use command line arguments to set hashing parameters.
+Either by setting them one by one (`-t` for time, `-m` for memory, `-p` for parallelism, `-l` for hash length), or by passing `--profile` followed by one of the names from {mod}`argon2.profiles`.
+In that case, the other parameters are ignored.
+If you don't pass any arguments as above, it runs with {class}`argon2.PasswordHasher`'s default values.
+
+This should make it much easier to determine the right parameters for your use case and your environment.

docs/conf.py

@@ -16,9 +16,7 @@
     "sphinx.ext.todo",
 ]
 
-myst_enable_extensions = [
-    "deflist",
-]
+myst_enable_extensions = ["deflist", "colon_fence"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.md

@@ -0,0 +1,36 @@
+# *argon2-cffi*: Argon2 for Python
+
+Release **{sub-ref}`release`**  ([What's new?](changelog))
+
+```{include} ../README.md
+:end-before: <!-- end-short -->
+:start-after: <!-- begin-short -->
+```
+
+
+## User's Guide
+
+```{toctree}
+:maxdepth: 1
+
+argon2
+installation
+api
+parameters
+cli
+faq
+changelog
+```
+
+
+## Project Information
+
+```{include} ../README.md
+:start-after: '## Project Information'
+```
+
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`search`

docs/installation.md

@@ -0,0 +1,73 @@
+# Installation
+
+## Using a Vendored Argon2
+
+```console
+$ python -Im pip install argon2-cffi
+```
+
+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.
+
+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.
+
+If something goes wrong, please try to update your *cffi*, *pip* and *setuptools* packages first:
+
+```console
+$ python -Im pip install -U cffi pip setuptools
+```
+
+Overall this should be the safest bet because *argon2-cffi* has been specifically tested against the vendored version.
+
+
+### Wheels
+
+Binary [wheels](https://pythonwheels.com) for macOS, Windows, and Linux are provided on [PyPI] by [argon2-cffi-bindings].
+With a recent-enough *pip* and *setuptools*, they should be used automatically.
+
+
+### Source Distribution
+
+A working C compiler and [CFFI environment] are required to build the [argon2-cffi-bindings] dependency.
+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
+
+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.
+
+Therefore you also have to instruct *pip* to use a source distribution of [argon2-cffi-bindings]:
+
+```console
+$ 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.
+
+**It is your own responsibility to deal with these risks if you choose this path.**
+
+Available since version 18.1.0.
+The `--no-binary` option value changed in 21.2.0 due to the outsourcing of the binary bindings.
+
+
+## Override Automatic SSE2 Detection
+
+Usually the build process tries to guess whether or not it should use [SSE2]-optimized code.
+Despite our best efforts, this can go wrong.
+
+Therefore you can use the `ARGON2_CFFI_USE_SSE2` environment variable to control the process:
+
+- If you set it to `1`, *argon2-cffi* will build **with** SSE2 support.
+- If you set it to `0`, *argon2-cffi* will build **without** SSE2 support.
+- If you set it to anything else, it will be ignored and *argon2-cffi* will try to guess.
+
+Available since version 20.1.0.
+
+[argon2-cffi-bindings]: https://github.com/hynek/argon2-cffi-bindings
+[cffi environment]: https://cffi.readthedocs.io/en/latest/installation.html
+[pypi]: https://pypi.org/project/argon2-cffi-bindings/
+[sse2]: https://en.wikipedia.org/wiki/SSE2