From 454860efef57abb3936f3b3540ebb5bf6ae87216 Mon Sep 17 00:00:00 2001
From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date: Wed, 5 Feb 2020 19:51:09 +0100
Subject: [PATCH] Be more explicit about passwords in man pages
Prompted by an inquiry in #154.
---
doc/man/man3/crypto_blake2b.3monocypher | 26 ++++++++++++++++---
doc/man/man3/intro.3monocypher | 14 +++++-----
.../man3/optional/crypto_sha512.3monocypher | 26 ++++++++++++++++---
3 files changed, 54 insertions(+), 12 deletions(-)
diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher
index 05e5a52..957692f 100644
--- a/doc/man/man3/crypto_blake2b.3monocypher
+++ b/doc/man/man3/crypto_blake2b.3monocypher
@@ -10,7 +10,7 @@
.\"
.\" Copyright (c) 2017-2019 Loup Vaillant
.\" Copyright (c) 2018 Michael Savage
-.\" Copyright (c) 2017, 2019 Fabio Scotoni
+.\" Copyright (c) 2017, 2020 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
@@ -40,7 +40,7 @@
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" Written in 2017-2019 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2020 by Loup Vaillant, Michael Savage and Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
.\" with this software. If not, see
.\"
.\"
-.Dd December 12, 2019
+.Dd February 5, 2020
.Dt CRYPTO_BLAKE2B 3MONOCYPHER
.Os
.Sh NAME
@@ -104,6 +104,11 @@
BLAKE2b is a fast cryptographically secure hash, based on the ideas of
Chacha20.
It is faster than MD5, yet just as secure as SHA-3.
+However, BLAKE2b itself
+.Sy is not suitable for hashing and deriving keys from passwords ;
+use the
+.Xr crypto_argon2i 3monocypher
+family of functions for that purpose instead.
.Pp
BLAKE2b is immune to length extension attacks, and as such does not
require any specific precautions, such as using the HMAC algorithm.
@@ -276,3 +281,18 @@ Any deviation from the specified input and output length ranges results
in
.Sy undefined behaviour .
Make sure your inputs are correct.
+.Sh SECURITY CONSIDERATIONS
+BLAKE2b is a general-purpose cryptographic hash function;
+this means that it is not suited for hashing passwords and deriving
+cryptographic keys from passwords in particular.
+While cryptographic keys usually have hundreds of bits of entropy,
+passwords are often much less complex.
+When storing passwords as hashes or when deriving keys from them,
+the goal is normally to prevent attackers from quickly iterating all
+possible passwords.
+Because passwords tend to be simple,
+it is important to artificially slow down attackers by using especially
+computationally difficult hashing algorithms.
+Monocypher therefore provides
+.Xr crypto_argon2i 3monocypher
+for password hashing and deriving keys from passwords.
diff --git a/doc/man/man3/intro.3monocypher b/doc/man/man3/intro.3monocypher
index 90625a0..1dd1077 100644
--- a/doc/man/man3/intro.3monocypher
+++ b/doc/man/man3/intro.3monocypher
@@ -10,7 +10,7 @@
.\"
.\" Copyright (c) 2017-2019 Loup Vaillant
.\" Copyright (c) 2018 Michael Savage
-.\" Copyright (c) 2017, 2019 Fabio Scotoni
+.\" Copyright (c) 2017, 2019-2020 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
@@ -40,7 +40,7 @@
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" Written in 2017-2019 by Loup Vaillant, Michael Savage and Fabio Scotoni
+.\" Written in 2017-2020 by Loup Vaillant, Michael Savage and Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
@@ -50,7 +50,7 @@
.\" with this software. If not, see
.\"
.\"
-.Dd December 12, 2019
+.Dd February 5, 2020
.Dt INTRO 3MONOCYPHER
.Os
.Sh NAME
@@ -59,7 +59,7 @@
.Sh DESCRIPTION
Monocypher is a cryptographic library.
It provides functions for authenticated encryption, hashing, password
-key derivation, key exchange, and public key signatures.
+hashing and key derivation, key exchange, and public key signatures.
.Ss Authenticated encryption
.Xr crypto_lock 3monocypher
and
@@ -88,9 +88,11 @@ implements the Blake2b hash.
Blake2b combines the security of SHA-3 and the speed of MD5.
It is immune to length extension attacks and provides a keyed mode
that makes it a safe, easy to use authenticator.
-.Ss Password key derivation
+.Ss Password hashing and key derivation
.Xr crypto_argon2i 3monocypher
-implements the Argon2i resource intensive hash algorithm.
+implements the Argon2i resource intensive hash algorithm,
+which can be used to hash passwords for storage and to derive keys
+from passwords.
Argon2 won the password hashing competition in 2015.
Unlike Scrypt, Argon2i is immune to timing attacks.
.Ss Key exchange
diff --git a/doc/man/man3/optional/crypto_sha512.3monocypher b/doc/man/man3/optional/crypto_sha512.3monocypher
index 6debeaf..0235774 100644
--- a/doc/man/man3/optional/crypto_sha512.3monocypher
+++ b/doc/man/man3/optional/crypto_sha512.3monocypher
@@ -8,7 +8,7 @@
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" Copyright (c) 2019 Fabio Scotoni
+.\" Copyright (c) 2019-2020 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
@@ -38,7 +38,7 @@
.\"
.\" ----------------------------------------------------------------------------
.\"
-.\" Written in 2019 by Fabio Scotoni
+.\" Written in 2019-2020 by Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
@@ -48,7 +48,7 @@
.\" with this software. If not, see
.\"
.\"
-.Dd December 12, 2019
+.Dd February 5, 2020
.Dt CRYPTO_SHA512 3MONOCYPHER
.Os
.Sh NAME
@@ -88,6 +88,11 @@ It is generally recommended to use
instead,
as it both performs faster on x86_64 CPUs and
lacks many of the pitfalls of SHA-512.
+However, SHA-512 itself
+.Sy is not suitable for hashing and deriving keys from passwords ;
+use the
+.Xr crypto_argon2i 3monocypher
+family of functions for that purpose instead.
.Pp
SHA-512 is
.Em vulnerable to length extension attacks ;
@@ -190,3 +195,18 @@ functions first appeared in Monocypher 0.3;
they were not intended for use outside Monocypher itself and thus
undocumented.
They became part of the official API in Monocypher 3.0.0.
+.Sh SECURITY CONSIDERATIONS
+SHA-512 is a general-purpose cryptographic hash function;
+this means that it is not suited for hashing passwords and deriving
+cryptographic keys from passwords in particular.
+While cryptographic keys usually have hundreds of bits of entropy,
+passwords are often much less complex.
+When storing passwords as hashes or when deriving keys from them,
+the goal is normally to prevent attackers from quickly iterating all
+possible passwords.
+Because passwords tend to be simple,
+it is important to artificially slow down attackers by using especially
+computationally difficult hashing algorithms.
+Monocypher therefore provides
+.Xr crypto_argon2i 3monocypher
+for password hashing and deriving keys from passwords.
--
2.47.3