mirror of
https://github.com/apache/nuttx.git
synced 2026-05-12 01:42:49 +08:00
!Documentation: describe build-time passwd generation workflow.
Build Documentation / build-html (push) Has been cancelled
Build Documentation / build-html (push) Has been cancelled
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 <mishra.abhishek2808@gmail.com>
This commit is contained in:
Abhishek Mishra
committed by
Xiang Xiao
Xiang Xiao
parent
86a7fa9246
commit
ba6a4d55fe
@@ -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``.
|
||||
@@ -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:
|
||||
|
||||
|
||||
+14
-10
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
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_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)
|
||||
|
||||
.. code:: console
|
||||
The password is hashed with TEA at build time by the host tool
|
||||
``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
|
||||
|
||||
nsh> cat /etc/passwd
|
||||
admin:8Tv+Hbmr3pLVb5HHZgd26D:0:0:/
|
||||
|
||||
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 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
|
||||
|
||||
Reference in New Issue
Block a user