.TH USERGEN 1 2025-10-08 0.4.0 "slcl user manual"

.SH NAME
usergen \- append a user into a slcl database

.SH SYNOPSIS
.B usergen
dir

.SH DESCRIPTION
.B usergen
performs the following steps:

.B 1.
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, 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
.B users
key in
.BR dir/db.json .

.B 4.
Creates a directory with the username in
.BR dir/user/ .

.SH OPTIONS
.B dir
defines the directory where
.B db.json
is located.

.SH NOTES
For security reasons, passwords are never stored in plaintext into
.BR dir/db.json .
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

Below, there is an example of a new user called
.B johndoe
with password
.B secret
(not echoed to the terminal) and a specified quota of 512 MiB:

.PP
.EX
$ ./usergen ~/db
./usergen ~/db
Username:
johndoe
Password:

Quota, in MiB (leave empty for unlimited quota):
512
Password hashing (sha256 [deprecated], argon2id): [argon2id]

.EE

Then,
.B dir/db.json
should be updated to something similar to:

.PP
.in +4n
.EX
{
	"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-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
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

.SH SEE ALSO

.B slcl(1)