!Documentation: describe build-time passwd generation workflow.

Abhishek Mishra · Abhishek Mishra · commit f0fb734f5fde · 2026-04-13T19:53:42.000Z
Document the new mkpasswd-based password generation system and its
integration with the build process.

Changes:
* Add comprehensive mkpasswd tool documentation to components/tools
* Update SIM board docs to explain generated passwd workflow
* Update ESP32-C3-legacy board docs for passwd generation
* Update RX65N board docs with credential handling guidance
* Document how to configure and use BOARD_ETC_ROMFS_PASSWD_* options
* Explain security benefits of build-time generation vs static files
* Update all doc examples from default username "admin" to "root"

BREAKING CHANGE: Boards using static /etc/passwd files in ETC_ROMFS
must migrate to the new build-time generation workflow documented in
Documentation/components/tools/index.rst. The old static passwd files
are no longer present in migrated boards; boards that relied on them
will fail to build until credentials are configured via Kconfig.

Signed-off-by: Abhishek Mishra &lt;mishra.abhishek2808@gmail.com&gt;
diff --git a/Documentation/components/tools/index.rst b/Documentation/components/tools/index.rst
@@ -11,3 +11,113 @@ and host C programs that are important parts of the NuttX build system:
    :glob:
 
    ./*
+
+.. _mkpasswd_autogen:
+
+mkpasswd — Build-time ``/etc/passwd`` Generation
+-------------------------------------------------
+
+``tools/mkpasswd`` is a C host tool (compiled from ``tools/mkpasswd.c``) that
+generates a single ``/etc/passwd`` entry at build time.  It is invoked
+automatically by the ROMFS build step when
+``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y`` is set.
+
+Why build-time generation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Shipping a hard-coded default password in firmware is a well-known security
+weakness (CWE-798).  By generating the ``/etc/passwd`` entry from a
+user-supplied plaintext password at build time, each firmware image carries
+unique credentials.  The build will fail if the password is left empty,
+preventing accidental deployments with no credentials.
+
+For improved baseline security, the configured password must be at least
+8 characters long.
+
+How it works
+~~~~~~~~~~~~
+
+1. The host tool reads the plaintext password from
+   ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``.
+2. The password is hashed using the Tiny Encryption Algorithm (TEA) — the
+   same implementation used at runtime in
+   ``libs/libc/misc/lib_tea_encrypt.c`` — with custom base64 encoding
+   matching ``apps/fsutils/passwd/passwd_encrypt.c``.
+3. The resulting hashed entry is written to
+   ``etctmp/<mountpoint>/passwd`` and then embedded into the ROMFS image.
+4. The **plaintext password is never stored in the firmware image**.
+
+Kconfig options
+~~~~~~~~~~~~~~~
+
+Enable the feature and configure credentials via ``make menuconfig``:
+
+.. code:: kconfig
+
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
+   CONFIG_NSH_CONSOLE_LOGIN=y                     # required to enforce login prompt
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_USER="root"          # default: root
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD="<secret>"  # required, min length 8
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_UID=0
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_GID=0
+   CONFIG_BOARD_ETC_ROMFS_PASSWD_HOME="/"
+
+The TEA encryption keys can be changed from their defaults via
+``CONFIG_FSUTILS_PASSWD_KEY1..4``.
+
+``/etc/passwd`` file format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: text
+
+   user:x:uid:gid:home
+
+Where:
+
+* ``user`` — user name
+* ``x`` — TEA-hashed, base64-encoded password
+* ``uid`` — numeric user ID
+* ``gid`` — numeric group ID
+* ``home`` — login directory
+
+Verifying the generated entry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After enabling ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` and setting a
+password, rebuild and verify:
+
+1. **Configure and build**:
+
+   .. code:: console
+
+      $ make menuconfig   # enable BOARD_ETC_ROMFS_PASSWD_ENABLE and set password
+      $ make
+
+2. **Inspect the generated passwd line** (written to the board build tree):
+
+   .. code:: console
+
+      $ cat boards/<arch>/<chip>/<board>/src/etctmp/etc/passwd
+      root:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
+
+3. **Verify the plaintext is absent from firmware**:
+
+   .. code:: console
+
+      $ grep <your-password> boards/<arch>/<chip>/<board>/src/etctmp.c
+      # must print nothing
+
+Notes on ``savedefconfig``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To avoid leaking credentials into board defconfigs, ``make savedefconfig``
+does not save the following options in the generated defconfig:
+
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``
+* ``CONFIG_FSUTILS_PASSWD_KEY1``
+* ``CONFIG_FSUTILS_PASSWD_KEY2``
+* ``CONFIG_FSUTILS_PASSWD_KEY3``
+* ``CONFIG_FSUTILS_PASSWD_KEY4``
+
+If you need these values for local development, add them manually to your
+local defconfig after running ``make savedefconfig``.
diff --git a/Documentation/platforms/renesas/rx65n/boards/rx65n-grrose/index.rst b/Documentation/platforms/renesas/rx65n/boards/rx65n-grrose/index.rst
@@ -491,21 +491,21 @@ mounted at /etc and will look like this at run-time:
    nsh>
 
 ``/etc/init.d/rc.sysinit`` is system init script; ``/etc/init.d/rcS`` is the
-start-up script; ``/etc/passwd`` is a the password file. It supports a single
-user:
+start-up script; ``/etc/passwd`` is the password file.
 
-.. code:: text
+The ``/etc/passwd`` file is auto-generated at build time when
+``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set.  Enable the option and set
+credentials via ``make menuconfig``:
 
-   USERNAME:  admin
-   PASSWORD:  Administrator
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``root``)
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required, build fails if empty)
 
-   nsh> cat /etc/passwd
-   admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
+The password is hashed with TEA at build time by the host tool
+``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
 
-The encrypted passwords in the provided passwd file are only valid if the TEA
-key is set to: 012345678 9abcdef0 012345678 9abcdef0. Changes to either the key
-or the password word will require regeneration of the ``nsh_romfimg.h`` header
-file.
+For the full description of the mechanism, TEA key configuration, file format,
+and verification steps, see :ref:`mkpasswd_autogen`.
 
 The format of the password file is:
 
diff --git a/Documentation/platforms/risc-v/esp32c3-legacy/boards/esp32c3-legacy-devkit/ROMFS.txt b/Documentation/platforms/risc-v/esp32c3-legacy/boards/esp32c3-legacy-devkit/ROMFS.txt
@@ -9,7 +9,7 @@ README
   that will be mounted at /etc and will look like this at run-time:
 
     NuttShell (NSH) NuttX-10.1.0-RC1
-    MOTD: username=admin password=Administrator
+    NuttX login. Configure credentials via make menuconfig.
     nsh> ls -Rl /etc
     /etc:
      dr-xr-xr-x       0 .
@@ -23,18 +23,22 @@ README
     nsh>
 
   /etc/init.d/rc.sysinit is system init script; /etc/init.d/rcS is the start-up
-  script; /etc/passwd is a the password file.  It supports a single user:
+  script; /etc/passwd is the password file.
 
-    USERNAME:  admin
-    PASSWORD:  Administrator
+  The /etc/passwd file is auto-generated at build time when
+  CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE is set.  To configure the root user and
+  password, run 'make menuconfig' and set:
 
-    nsh> cat /etc/passwd
-    admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
+    CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
+    CONFIG_BOARD_ETC_ROMFS_PASSWD_USER (default: root)
+    CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD (required, build fails if empty)
 
-  The encrypted passwords in the provided passwd file are only valid if the
-  TEA key is set to:  012345678 9abcdef0 012345678 9abcdef0.  Changes to either
-  the key or the password word will require regeneration of the nsh_romfimg.h
-  header file.
+  The password is hashed with TEA at build time by the host tool
+  tools/mkpasswd; the plaintext is NOT stored in the firmware image.
+
+  For the full description of the mechanism, TEA key configuration, file
+  format, and verification steps, see Documentation/components/tools/index.rst
+  (mkpasswd section).
 
   The format of the password file is:
 
diff --git a/Documentation/platforms/sim/sim/boards/sim/index.rst b/Documentation/platforms/sim/sim/boards/sim/index.rst
@@ -1903,13 +1903,13 @@ This is a configuration with login password protection for NSH.
 
 .. note::
 
-   This config has password protection enabled. The login info is:
+   This config has password protection enabled. The default login info is:
 
-   * USERNAME: admin
+   * USERNAME: root
    * PASSWORD: Administrator
 
-   The encrypted password is retained in ``/etc/passwd``. I am sure that you
-   will find this annoying. You can disable the password protection by
+   The encrypted password is retained in ``/etc/passwd``.
+   You can disable the password protection by
    de-selecting ``CONFIG_NSH_CONSOLE_LOGIN=y``.
 
 can
@@ -2021,24 +2021,23 @@ mounted at ``/etc`` and will look like this at run-time:
    nsh>
 
 ``/etc/init.d/rc.sysinit`` is system init script; ``/etc/init.d/rcS`` is the
-start-up script; ``/etc/passwd`` is a the password file. It supports a single
-user:
+start-up script; ``/etc/passwd`` is the password file.
 
-.. code:: text
-
-   USERNAME:  admin
-   PASSWORD:  Administrator
-
-.. code:: console
+The ``/etc/passwd`` file is auto-generated at build time when
+``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set.  Enable the option and set
+credentials via ``make menuconfig``:
 
-   nsh> cat /etc/passwd
-   admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
+* ``CONFIG_NSH_CONSOLE_LOGIN=y`` (required, otherwise login is not enforced)
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``root``)
+* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required, build fails if empty or shorter than 8 characters)
 
-The encrypted passwords in the provided passwd file are only valid if the
-TEA key is set to: 012345678 9abcdef0 012345678 9abcdef0.
+The password is hashed with TEA at build time by the host tool
+``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
 
-Changes to either the key or the password word will require regeneration of the
-``nsh_romfimg.h`` header file.
+For the full description of the build-time password generation mechanism,
+TEA key configuration, file format, and verification steps, see
+:ref:`mkpasswd_autogen`.
 
 The format of the password file is:
 
@@ -2054,6 +2053,21 @@ Where:
 * gid: Group ID (0 for now)
 * home: Login directory (/ for now)
 
+For configuration, verification steps, and TEA key details, see
+:ref:`mkpasswd_autogen`.
+
+Login test inside the simulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: console
+
+   $ ./nuttx
+   NuttShell (NSH) NuttX-<version>
+   nsh login: root
+   Password:
+   User Logged-in!
+   nsh>
+
 ``/etc/group`` is a group file. It is not currently used.
 
 .. code:: console
