From 10e42591ac72285736d5cc4ee5e7c2f68dbf1e4b Mon Sep 17 00:00:00 2001 From: Xavier Del Campo Romero Date: Wed, 8 Oct 2025 13:50:52 +0200 Subject: 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 --- doc/man1/usergen.1 | 74 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 21 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3