Skip to content

Commit 739a0a2

Browse files
author
Abhishek Mishra
committed
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 Helps users understand password configuration and security implications. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
1 parent be5f31c commit 739a0a2

4 files changed

Lines changed: 162 additions & 34 deletions

File tree

‎Documentation/components/tools/index.rst‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,113 @@ and host C programs that are important parts of the NuttX build system:
1111
:glob:
1212

1313
./*
14+
15+
.. _mkpasswd_autogen:
16+
17+
mkpasswd — Build-time ``/etc/passwd`` Generation
18+
-------------------------------------------------
19+
20+
``tools/mkpasswd`` is a C host tool (compiled from ``tools/mkpasswd.c``) that
21+
generates a single ``/etc/passwd`` entry at build time. It is invoked
22+
automatically by the ROMFS build step when
23+
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y`` is set.
24+
25+
Why build-time generation?
26+
~~~~~~~~~~~~~~~~~~~~~~~~~~
27+
28+
Shipping a hard-coded default password in firmware is a well-known security
29+
weakness (CWE-798). By generating the ``/etc/passwd`` entry from a
30+
user-supplied plaintext password at build time, each firmware image carries
31+
unique credentials. The build will fail if the password is left empty,
32+
preventing accidental deployments with no credentials.
33+
34+
For improved baseline security, the configured password must be at least
35+
8 characters long.
36+
37+
How it works
38+
~~~~~~~~~~~~
39+
40+
1. The host tool reads the plaintext password from
41+
``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``.
42+
2. The password is hashed using the Tiny Encryption Algorithm (TEA) — the
43+
same implementation used at runtime in
44+
``libs/libc/misc/lib_tea_encrypt.c`` — with custom base64 encoding
45+
matching ``apps/fsutils/passwd/passwd_encrypt.c``.
46+
3. The resulting hashed entry is written to
47+
``etctmp/<mountpoint>/passwd`` and then embedded into the ROMFS image.
48+
4. The **plaintext password is never stored in the firmware image**.
49+
50+
Kconfig options
51+
~~~~~~~~~~~~~~~
52+
53+
Enable the feature and configure credentials via ``make menuconfig``:
54+
55+
.. code:: kconfig
56+
57+
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
58+
CONFIG_NSH_CONSOLE_LOGIN=y # required to enforce login prompt
59+
CONFIG_BOARD_ETC_ROMFS_PASSWD_USER="admin" # default: admin
60+
CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD="<secret>" # required, min length 8
61+
CONFIG_BOARD_ETC_ROMFS_PASSWD_UID=0
62+
CONFIG_BOARD_ETC_ROMFS_PASSWD_GID=0
63+
CONFIG_BOARD_ETC_ROMFS_PASSWD_HOME="/"
64+
65+
The TEA encryption keys can be changed from their defaults via
66+
``CONFIG_FSUTILS_PASSWD_KEY1..4``.
67+
68+
``/etc/passwd`` file format
69+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
.. code:: text
72+
73+
user:x:uid:gid:home
74+
75+
Where:
76+
77+
* ``user`` — user name
78+
* ``x`` — TEA-hashed, base64-encoded password
79+
* ``uid`` — numeric user ID
80+
* ``gid`` — numeric group ID
81+
* ``home`` — login directory
82+
83+
Verifying the generated entry
84+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85+
86+
After enabling ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` and setting a
87+
password, rebuild and verify:
88+
89+
1. **Configure and build**:
90+
91+
.. code:: console
92+
93+
$ make menuconfig # enable BOARD_ETC_ROMFS_PASSWD_ENABLE and set password
94+
$ make
95+
96+
2. **Inspect the generated passwd line** (written to the board build tree):
97+
98+
.. code:: console
99+
100+
$ cat boards/<arch>/<chip>/<board>/src/etctmp/etc/passwd
101+
admin:s1IZjGjjmo/x8u5m5uY2jB:0:0:/
102+
103+
3. **Verify the plaintext is absent from firmware**:
104+
105+
.. code:: console
106+
107+
$ grep <your-password> boards/<arch>/<chip>/<board>/src/etctmp.c
108+
# must print nothing
109+
110+
Notes on ``savedefconfig``
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
To avoid leaking credentials into board defconfigs, ``make savedefconfig``
114+
does not save the following options in the generated defconfig:
115+
116+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``
117+
* ``CONFIG_FSUTILS_PASSWD_KEY1``
118+
* ``CONFIG_FSUTILS_PASSWD_KEY2``
119+
* ``CONFIG_FSUTILS_PASSWD_KEY3``
120+
* ``CONFIG_FSUTILS_PASSWD_KEY4``
121+
122+
If you need these values for local development, add them manually to your
123+
local defconfig after running ``make savedefconfig``.

‎Documentation/platforms/renesas/rx65n/boards/rx65n-grrose/index.rst‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -491,21 +491,21 @@ mounted at /etc and will look like this at run-time:
491491
nsh>
492492
493493
``/etc/init.d/rc.sysinit`` is system init script; ``/etc/init.d/rcS`` is the
494-
start-up script; ``/etc/passwd`` is a the password file. It supports a single
495-
user:
494+
start-up script; ``/etc/passwd`` is the password file.
496495

497-
.. code:: text
496+
The ``/etc/passwd`` file is auto-generated at build time when
497+
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set. Enable the option and set
498+
credentials via ``make menuconfig``:
498499

499-
USERNAME: admin
500-
PASSWORD: Administrator
500+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
501+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``admin``)
502+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required, build fails if empty)
501503

502-
nsh> cat /etc/passwd
503-
admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
504+
The password is hashed with TEA at build time by the host tool
505+
``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
504506

505-
The encrypted passwords in the provided passwd file are only valid if the TEA
506-
key is set to: 012345678 9abcdef0 012345678 9abcdef0. Changes to either the key
507-
or the password word will require regeneration of the ``nsh_romfimg.h`` header
508-
file.
507+
For the full description of the mechanism, TEA key configuration, file format,
508+
and verification steps, see :ref:`mkpasswd_autogen`.
509509

510510
The format of the password file is:
511511

‎Documentation/platforms/risc-v/esp32c3-legacy/boards/esp32c3-legacy-devkit/ROMFS.txt‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,18 +23,22 @@ README
2323
nsh>
2424

2525
/etc/init.d/rc.sysinit is system init script; /etc/init.d/rcS is the start-up
26-
script; /etc/passwd is a the password file. It supports a single user:
26+
script; /etc/passwd is the password file.
2727

28-
USERNAME: admin
29-
PASSWORD: Administrator
28+
The /etc/passwd file is auto-generated at build time when
29+
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE is set. To configure the admin user and
30+
password, run 'make menuconfig' and set:
3031

31-
nsh> cat /etc/passwd
32-
admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
32+
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
33+
CONFIG_BOARD_ETC_ROMFS_PASSWD_USER (default: admin)
34+
CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD (required, build fails if empty)
3335

34-
The encrypted passwords in the provided passwd file are only valid if the
35-
TEA key is set to: 012345678 9abcdef0 012345678 9abcdef0. Changes to either
36-
the key or the password word will require regeneration of the nsh_romfimg.h
37-
header file.
36+
The password is hashed with TEA at build time by the host tool
37+
tools/mkpasswd; the plaintext is NOT stored in the firmware image.
38+
39+
For the full description of the mechanism, TEA key configuration, file
40+
format, and verification steps, see Documentation/components/tools/index.rst
41+
(mkpasswd section).
3842

3943
The format of the password file is:
4044

‎Documentation/platforms/sim/sim/boards/sim/index.rst‎

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2008,24 +2008,23 @@ mounted at ``/etc`` and will look like this at run-time:
20082008
nsh>
20092009
20102010
``/etc/init.d/rc.sysinit`` is system init script; ``/etc/init.d/rcS`` is the
2011-
start-up script; ``/etc/passwd`` is a the password file. It supports a single
2012-
user:
2011+
start-up script; ``/etc/passwd`` is the password file.
20132012

2014-
.. code:: text
2015-
2016-
USERNAME: admin
2017-
PASSWORD: Administrator
2018-
2019-
.. code:: console
2013+
The ``/etc/passwd`` file is auto-generated at build time when
2014+
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set. Enable the option and set
2015+
credentials via ``make menuconfig``:
20202016

2021-
nsh> cat /etc/passwd
2022-
admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
2017+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
2018+
* ``CONFIG_NSH_CONSOLE_LOGIN=y`` (required, otherwise login is not enforced)
2019+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``admin``)
2020+
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required, build fails if empty or shorter than 8 characters)
20232021

2024-
The encrypted passwords in the provided passwd file are only valid if the
2025-
TEA key is set to: 012345678 9abcdef0 012345678 9abcdef0.
2022+
The password is hashed with TEA at build time by the host tool
2023+
``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
20262024

2027-
Changes to either the key or the password word will require regeneration of the
2028-
``nsh_romfimg.h`` header file.
2025+
For the full description of the build-time password generation mechanism,
2026+
TEA key configuration, file format, and verification steps, see
2027+
:ref:`mkpasswd_autogen`.
20292028

20302029
The format of the password file is:
20312030

@@ -2041,6 +2040,21 @@ Where:
20412040
* gid: Group ID (0 for now)
20422041
* home: Login directory (/ for now)
20432042

2043+
For configuration, verification steps, and TEA key details, see
2044+
:ref:`mkpasswd_autogen`.
2045+
2046+
Login test inside the simulator
2047+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2048+
2049+
.. code:: console
2050+
2051+
$ ./nuttx
2052+
NuttShell (NSH) NuttX-<version>
2053+
nsh login: admin
2054+
Password:
2055+
User Logged-in!
2056+
nsh>
2057+
20442058
``/etc/group`` is a group file. It is not currently used.
20452059

20462060
.. code:: console

0 commit comments

Comments
 (0)