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

[Bastian Germann]

Am 05.07.22 um 11:06 schrieb 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>
> ---
>   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..58fa9a97f 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,

two spaces.

> +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 all supported Debian
> +releases.

bullseye is supported and has yescrypt as a default.
Please replace all with "most".

> +
> +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_hased` attribute for other users in

typo: passwd_hashed

> +`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`.

With the three suggested changes:
Reviewed-by: Bastian Germann <bage at linutronix.de>