Replace OpenSSL with libsodium and argon2id

The SHA256-based password hashing algorithm used by slcl(1) and
usergen(1) is considered insecure against several kinds of attacks,
including brute force attacks. [1]

Therefore, a stronger password hashing algorithm based on the Argon2id
key derivation function is now used by default. While OpenSSL does
support Argon2id, it is only supported by very recent versions [2],
which are still not packaged by most distributions as of the time of
this writing. [3]

As an alternative to OpenSSL, libsodium [4] had several benefits:

- It provides easy-to-use functions for password hashing, base64
encoding/decoding and other cryptographic primitives used by slcl(1)
and usergen(1).

- It is packaged by most distributions [5], and most often only the patch
version differs, which ensures good compatibility across distributions.

Unfortunately, and as opposed to OpenSSL, libsodium does not come with
command-line tools. Therefore, usergen(1) had to be rewritten in C.

In order to maintain backwards compatiblity with existing databases,
slcl(1) and usergen(1) shall support the insecure, SHA256-based password
hashing algorithm. However, Argon2id shall now be the default choice for
usergen(1).

[1]: https://security.stackexchange.com/questions/195563/why-is-sha-256-not-good-for-passwords
[2]: https://docs.openssl.org/3.3/man7/EVP_KDF-ARGON2/
[3]: https://repology.org/project/openssl/versions
[4]: https://www.libsodium.org/
[5]: https://repology.org/project/libsodium/versions

1 files changed, 53 insertions, 21 deletions

diff --git a/doc/man1/usergen.1 b/doc/man1/usergen.1
index 857d9df..1a52e31 100644
--- a/doc/man1/usergen.1
+++ b/doc/man1/usergen.1
@@ -1,4 +1,4 @@
-.TH USERGEN 1 usergen
+.TH USERGEN 1 2025-10-08 0.4.0 "slcl user manual"
 
 .SH NAME
 usergen \- append a user into a slcl database
@@ -12,11 +12,29 @@ dir
 performs the following steps:
 
 .B 1.
-Reads user credentials and quota from standard input.
+Reads user credentials, password hashing algorithm and quota from standard
+input.
+
+Two password hashing algorithms are defined:
+
+.IP \(bu 2
+.BR sha256 :
+a multi-round, SHA256-based hashing algorithm.
+.BR "It is deprecated and considered insecure" ,
+see
+.B NOTES
+for further reference.
+
+.IP \(bu 2
+.BR argon2id :
+considered more secure and enabled by default. It is based on the Argon2id
+key derivation function.
+
+.LP
 
 .B 2.
-Generates a JSON object with the read credentials and quota, as well as
-a random salt and signing key.
+Generates a JSON object with the read credentials, password hashing algorithm
+and quota, as well as a signing key and optional, algorithm-specific data.
 
 .B 3.
 Appends the newly generated JSON object into the
@@ -37,10 +55,21 @@ is located.
 .SH NOTES
 For security reasons, passwords are never stored in plaintext into
 .BR dir/db.json .
-Instead, a salted, multi-round hashed password is calculated and
-stored. Then,
-.B slcl(1)
-performs the same operations to ensure both tokens match.
+Historically,
+.IR usergen (1)
+and
+.IR slcl (1)
+relied on a salted, multi-round SHA256-based password hashing algorithm.
+However,
+.BR "this is considered insecure against brute-forcing and other attacks" .
+Therefore, since version 0.4.0, both
+.IR usergen (1)
+and
+.IR slcl (1)
+have been improved in order to support the more secure
+Argon2id key derivation function.
+Nevertheless, in order to keep backwards compatibility with existing
+databases, the older hashing algorithm is still supported.
 
 .SH EXAMPLES
 
@@ -48,18 +77,20 @@ Below, there is an example of a new user called
 .B johndoe
 with password
 .B secret
-and a specified quota of 512 MiB:
+(not echoed to the terminal) and a specified quota of 512 MiB:
 
 .PP
 .EX
 $ ./usergen ~/db
+./usergen ~/db
 Username:
 johndoe
 Password:
-secret
+
 Quota, in MiB (leave empty for unlimited quota):
 512
-1000/1000
+Password hashing (sha256 [deprecated], argon2id): [argon2id]
+
 .EE
 
 Then,
@@ -67,22 +98,23 @@ Then,
 should be updated to something similar to:
 
 .PP
+.in +4n
 .EX
 {
-  "users": [
-    {
-      "name": "johndoe",
-      "password": "4c48385ec2be4798dc772d3c8f5649d8411afbdfc4708ada79379e3562af5abb",
-      "salt": "835324df29527731f3faad663c58c3b19a07c193e97dc77f33e10d3942cdc91c",
-      "key": "d0ae360b9af1177ce73eef3f499eea2627cd61b69df79dcb7a5c70bc658a4e63",
-      "quota": "512"
-    }
-  ]
+	"users":	[{
+			"name":	"johndoe",
+			"key":	"2bce6ac030d0737d17678d073a3b16841f08abd2f3757fb463d14edf869cf1ff",
+			"method":	"argon2id",
+			"quota":	"512",
+			"password":	"$argon2id$v=19$m=65536,t=2,p=1$TV6tsKdVRyCO6U5a/5GVhw$eRO0T4wc0WYtnYTIIh84XThVB+J5BJOsOufLF/6JaV8"
+		}]
 }
 .EE
+.in
+.PP
 
 .SH COPYRIGHT
-Copyright (C) 2023 Xavier Del Campo Romero.
+Copyright (C) 2023-2025 Xavier Del Campo Romero
 .P
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU Affero General Public License as published by