From aefd6c6fdaff9dd43369a93d7c91246accf34164 Mon Sep 17 00:00:00 2001
From: Xavier Del Campo Romero <xavi.dcr@tutanota.com>
Date: Thu, 16 Mar 2023 01:55:43 +0100
Subject: [PATCH] Add man page for usergen(1)

---
 doc/man1/slcl.1    |  3 ++
 doc/man1/usergen.1 | 92 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+)
 create mode 100644 doc/man1/usergen.1

diff --git a/doc/man1/slcl.1 b/doc/man1/slcl.1
index c050e01..3257f1c 100644
--- a/doc/man1/slcl.1
+++ b/doc/man1/slcl.1
@@ -122,3 +122,6 @@ Written by Xavier Del Campo Romero.
 
 .SH TODO
 Allow deleting files and directories from the web interface.
+
+.SH SEE ALSO
+.B usergen(1)
diff --git a/doc/man1/usergen.1 b/doc/man1/usergen.1
new file mode 100644
index 0000000..abe16f3
--- /dev/null
+++ b/doc/man1/usergen.1
@@ -0,0 +1,92 @@
+.TH USERGEN 1 usergen
+
+.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 and quota from standard input.
+
+.B 2.
+Generates a JSON object with the read credentials and quota, as well as
+a random salt and signing key.
+
+.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 .
+Instead, a salted, multi-round hashed password is calculated and
+stored. Then,
+.B slcl(1)
+performs the same operations to ensure both tokens match.
+
+.SH EXAMPLES
+
+Below, there is an example of a new user called
+.B johndoe
+with password
+.B secret
+and a specified quota of 512 MiB:
+
+.PP
+.EX
+$ ./usergen ~/db
+Username:
+johndoe
+Password:
+secret
+Quota, in MiB (leave empty for unlimited quota):
+512
+1000/1000
+.EE
+
+Then,
+.B dir/db.json
+should be updated to something similar to:
+
+.PP
+.EX
+{
+  "users": [
+    {
+      "name": "johndoe",
+      "password": "4c48385ec2be4798dc772d3c8f5649d8411afbdfc4708ada79379e3562af5abb",
+      "salt": "835324df29527731f3faad663c58c3b19a07c193e97dc77f33e10d3942cdc91c",
+      "key": "d0ae360b9af1177ce73eef3f499eea2627cd61b69df79dcb7a5c70bc658a4e63",
+      "quota": "512"
+    }
+  ]
+}
+.EE
+
+.SH LICENSE
+See the LICENSE file for further reference.
+
+.SH AUTHORS
+Written by Xavier Del Campo Romero.
+
+.SH SEE ALSO
+
+.B slcl(1)