From 4e3de90cd0b4350fa950f6bd0080ca4244f37128 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Fri, 1 Dec 2023 18:01:58 +0100
Subject: [PATCH] [users] Document password settings

---
 src/modules/users/users.conf | 62 +++++++++++++++++++++++++++---------
 1 file changed, 47 insertions(+), 15 deletions(-)

diff --git a/src/modules/users/users.conf b/src/modules/users/users.conf
index e16233057..669cac038 100644
--- a/src/modules/users/users.conf
+++ b/src/modules/users/users.conf
@@ -112,20 +112,19 @@ doAutologin:     true
 # on the user. The values given in this sample file set only very weak
 # validation settings.
 #
-# - nonempty rejects empty passwords
-# - there are no length validations
-# - libpwquality (if it is enabled at all) has no length of class
-#   restrictions, although it will still reject palindromes and
-#   dictionary words with these settings.
-#
-# Checks may be listed multiple times; each is checked separately,
-# and no effort is done to ensure that the checks are consistent
+# Calamares itself supports two checks:
+#   - minLength
+#   - maxLength
+# In this sample file, the values are set to -1 which means "no
+# minimum", "no maximum". This allows any password at all.
+# No effort is done to ensure that the checks are consistent
 # (e.g. specifying a maximum length less than the minimum length
 # will annoy users).
 #
+# Calamares supports password checking through libpwquality.
 # The libpwquality check relies on the (optional) libpwquality library.
-# Its value is a list of configuration statements that could also
-# be found in pwquality.conf, and these are handed off to the
+# The value for libpwquality is a list of configuration statements like
+# those found in pwquality.conf. The statements are handed off to the
 # libpwquality parser for evaluation. The check is ignored if
 # libpwquality is not available at build time (generates a warning in
 # the log). The Calamares password check rejects passwords with a
@@ -134,20 +133,51 @@ doAutologin:     true
 # (additional checks may be implemented in CheckPWQuality.cpp and
 # wired into UsersPage.cpp)
 #
-#  - To disable specific password validations:
-#    comment out the relevant 'passwordRequirements' keys below.
-#  - To disable all password validations:
-#    set both 'allowWeakPasswords' and 'allowWeakPasswordsDefault' to true.
+# To disable all password validations:
+#  - comment out the relevant 'passwordRequirements' keys below,
+#    or set minLength and maxLength to -1.
+#  - disable libpwquality at build-time.
+# To allow all passwords, but provide warnings:
+#  - set both 'allowWeakPasswords' and 'allowWeakPasswordsDefault' to true.
 #    (That will show the box *Allow weak passwords* in the user-
 #    interface, and check it by default).
+#  - configure password-checking however you wish.
+# To require specific password characteristics:
+#  - set 'allowWeakPasswords' to false (the default)
+#  - configure password-checking, e.g. with NIST settings
+
+
+# These are very weak -- actually, none at all -- requirements
 passwordRequirements:
-    nonempty: true
     minLength: -1  # Password at least this many characters
     maxLength: -1  # Password at most this many characters
     libpwquality:
         - minlen=0
         - minclass=0
 
+# These are "you must have a password, any password" -- requirements
+#
+# passwordRequirements:
+#     minLength: 1
+
+# These are requirements the try to follow the suggestions from
+#     https://pages.nist.gov/800-63-3/sp800-63b.html , "Digital Identity Guidelines".
+# Note that requiring long and complex passwords has its own cost,
+# because the user has to come up with one at install time.
+# Setting 'allowWeakPasswords' to false and 'doAutologin' to false
+# will require a strong password and prevent (graphical) login
+# without the password. It is likely to be annoying for casual users.
+#
+# passwordRequirements:
+#     minLength: 8
+#     maxLength: 64
+#     libpwquality:
+#         - minlen=8
+#         - maxrepeat=3
+#         - maxsequence=3
+#         - usersubstr=4
+#         - badwords=linux
+
 # You can control the visibility of the 'strong passwords' checkbox here.
 # Possible values are:
 #  - true to show or
@@ -165,6 +195,7 @@ allowWeakPasswords: false
 # to be unchecked.
 allowWeakPasswordsDefault: false
 
+
 # User settings
 #
 # The user can enter a username, but there are some other
@@ -187,6 +218,7 @@ user:
   shell: /bin/bash
   forbidden_names: [ root ]
 
+
 # Hostname settings
 #
 # The user can enter a hostname; this is configured into the system