[elbe-devel] [PATCH v2 1/1] docs: Describe the password handling in XMLs

[Holger Dengler]

Describe the usage of plain-text and hashed passwords for root and other
users in Elbe XMLs, the generation of hashed passwords and how to
include them into the XMLs.

Signed-off-by: Holger Dengler <holger at hdengler.de>
Reviewed-by: Bastian Germann <bage at linutronix.de>
---
 docs/elbeoverview-en.txt | 65 +++++++++++++++++++++++++++++++++++++++-
 docs/quickstart.txt      | 21 +++++++++++++
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/docs/elbeoverview-en.txt b/docs/elbeoverview-en.txt
index 6560d8b96..dced5f9e5 100644
--- a/docs/elbeoverview-en.txt
+++ b/docs/elbeoverview-en.txt
@@ -232,6 +232,68 @@ If an initvm has not been created yet, use:
 elbe initvm create --directory ~/elbe-initvm example.xml
 -----------------------------------------------------
 
+Passwords in XML
+~~~~~~~~~~~~~~~~
+
+Using plain-text passwords in XML has advantages and disadvantages. The main
+advantage is the documentation of the login credentials for the generated
+systems. But storing plain-text passwords on a system is a significant
+weakening of system security. For that reason, all XML files, which are
+generated by Elbe during the build process (`/etc/elbe_base.xml` and
+`source.xml`) contain only hashed passwords.
+
+If a plain-text password for root or a user is specified in the input XML,
+it is converted into a hashed password during the XML preprocessing. The
+preprocessed XML only contains the hashed password, the plain-text password
+will be removed. The XML preprocessing only supports the hashing method
+`sha512crypt` at the moment, which is the default in most of the supported
+Debian releases.
+
+Hashed passwords can be used right from the start and directly placed into
+the input XML. A plain-text password can be hashed with the tool `mkpasswd`
+or with various hashing libraries like crypt (C/C++) or passlib (Python).
+If the hashed passwords are generated manually, all hashing methods can be
+used, which are supported by the PAM configuration on the target system. If
+unsure, `sha512crypt` should be used.
+
+The following example uses the tool `mkpasswd` to hash the password. The
+tool will ask for a plain-text password (in this example "foo").
+
+------------------------------------------------------------------------------
+mkpasswd --method=sha512crypt --rounds=656000
+Password:
+$6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70
+------------------------------------------------------------------------------
+
+The generated line contains the hashing parameters and the hashed password
+and has to be copied completely to the XML, either as `passwd_hashed` node
+for the root password or as `passwd_hashed` attribute for other users in
+`adduser` nodes.
+
+[source,xml]
+------------------------------------------------------------------------------
+<target>
+	<!-- hashed password for root -->
+	<passwd_hashed>$6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70</passwd_hashed>
+</target>
+------------------------------------------------------------------------------
+
+[source,xml]
+------------------------------------------------------------------------------
+<finetuning>
+	<!-- hashed password for user elbe -->
+	<adduser passwd_hashed="$6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70" shell="/bin/bash">elbe</adduser>
+</finetuning>
+------------------------------------------------------------------------------
+
+.Note
+**********************************************************
+If the XML contains an action `login`, the password for
+the root login must be given in plain-text. This
+plain-text password will not be removed by the
+preprocessing and will stay also in the generated XML
+files `/etc/elbe_base.xml` and `source.xml`.
+**********************************************************
 
 Changing the subset that is extracted as the root filesystem
 ------------------------------------------------------------
@@ -685,7 +747,8 @@ source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 <2> and domainname
 
-<3> This is the root password of the machine.
+<3> This is the plain-text root password of the machine. It will be
+    converted into a hashed password by the XML preprocessing.
 
 <4> This describes, that the resulting rootfilesystem, shall be generated as
     'nfsroot.tar.gz'
diff --git a/docs/quickstart.txt b/docs/quickstart.txt
index 0a15b2b34..4ef0bacff 100644
--- a/docs/quickstart.txt
+++ b/docs/quickstart.txt
@@ -256,6 +256,27 @@ It is also possible to specify groups the new user should be part of:
 <adduser passwd="foo" shell="/bin/bash" groups="audio,video,dialout">elbe</adduser>
 ------------------------------------------------------------------------------
 
+Instead of specifying a plain-text password, it is also possible to use
+hashed passwords in the XML. Hashed passwords can be either converted by the
+Elbe preprocessing (`elbe preprocess <xml>`), with the tool `mkpasswd` or
+with various hashing libraries like crypt (C/C++) or passlib (Python).
+
+In this example, the command `mkpasswd` is used to hash the plain-text
+password `elbe`. If the salt is not specified, `mkpasswd` will use a random
+salt.
+
+------------------------------------------------------------------------------
+mkpasswd --method=sha512crypt --rounds=656000 --salt=7vWuOPVX0YKaISh5 "elbe"
+------------------------------------------------------------------------------
+
+The generated line contains the hashing parameters and the hashed password
+and has to be copied completely to the `passwd_hashed` attribute in the XML.
+
+[source,xml]
+------------------------------------------------------------------------------
+<adduser passwd_hashed="$6$rounds=656000$7vWuOPVX0YKaISh5$cJhevq/z7kJ215n18dnksv/zOeUf6uPoLgICwLeTSu/2xoLHkyYQABaM7a99sQmpilCV.SlK9jfHZz3m7/s2a." shell="/bin/bash">elbe</adduser>
+------------------------------------------------------------------------------
+
 Changing ownership of directories or files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 There is currently no special finetuning node for `chmod` and `chown`.
-- 
2.36.1