This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit ba6a4d55fe91c8ce8dba56905c7a8dd4c80ec006 Author: Abhishek Mishra <[email protected]> AuthorDate: Mon Apr 13 19:53:42 2026 +0000 !Documentation: describe build-time passwd generation workflow. 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 <[email protected]> --- Documentation/components/tools/index.rst | 110 +++++++++++++++++++++ .../renesas/rx65n/boards/rx65n-grrose/index.rst | 22 ++--- .../boards/esp32c3-legacy-devkit/ROMFS.txt | 24 +++-- .../platforms/sim/sim/boards/sim/index.rst | 50 ++++++---- 4 files changed, 167 insertions(+), 39 deletions(-) diff --git a/Documentation/components/tools/index.rst b/Documentation/components/tools/index.rst index ee6e5cd65c9..83c868984fb 100644 --- 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``. \ No newline at end of file diff --git a/Documentation/platforms/renesas/rx65n/boards/rx65n-grrose/index.rst b/Documentation/platforms/renesas/rx65n/boards/rx65n-grrose/index.rst index 38c646e15f7..537542c9394 100644 --- 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 index 5cc8e382a9c..2434964afdd 100644 --- 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 + This is an example NuttX Message Of The Day (MOTD). Have fun! 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 index 376081c12db..c2487ba2ed9 100644 --- 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
