mirror of
https://github.com/apache/nuttx.git
synced 2026-08-01 20:28:58 +00:00
Documentation: PBKDF2 login docs, board Kconfig, and CI password
Document PBKDF2-HMAC-SHA256 ROMFS passwd generation and update board Kconfig help text accordingly. Set the documented sim/login CI credential in GitHub Actions. Enable CONFIG_CODECS_BASE64 and CONFIG_NETUTILS_CODECS on sim:dropbear for link compatibility with dropbear's bundled libtomcrypt. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
This commit is contained in:
Abhishek Mishra
Xiang Xiao
parent
cb3954e70b
commit
6283d667ea
56 changed files with 566 additions and 264 deletions
|
|
@ -1745,8 +1745,7 @@ This command is available only when ``CONFIG_SCHED_USER_IDENTITY`` is
|
|||
enabled. It may be disabled with ``CONFIG_NSH_DISABLE_SU``. User names
|
||||
are looked up from the passwd database when ``CONFIG_LIBC_PASSWD_FILE``
|
||||
is enabled. Password verification requires one of the NSH login options
|
||||
(``CONFIG_NSH_LOGIN_PASSWD``, ``CONFIG_NSH_LOGIN_PLATFORM``, or
|
||||
``CONFIG_NSH_LOGIN_FIXED``).
|
||||
(``CONFIG_NSH_LOGIN_PASSWD`` or ``CONFIG_NSH_LOGIN_PLATFORM``).
|
||||
|
||||
**Related configuration**
|
||||
|
||||
|
|
|
|||
|
|
@ -18,13 +18,33 @@ Logins for Telnet sessions can be enabled separately with::
|
|||
Logins can be enabled for either or both session types. On a successful
|
||||
login, the user will have access to the NSH session::
|
||||
|
||||
login: admin
|
||||
login: root
|
||||
password:
|
||||
User Logged-in!
|
||||
|
||||
NuttShell (NSH)
|
||||
nsh>
|
||||
|
||||
ROMFS password file (recommended)
|
||||
==================================
|
||||
|
||||
Boards with ROMFS ``/etc`` should auto-generate ``/etc/passwd`` at build time::
|
||||
|
||||
CONFIG_ETC_ROMFS=y
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
|
||||
CONFIG_CRYPTO_CRYPTODEV=y
|
||||
CONFIG_FSUTILS_PASSWD=y
|
||||
CONFIG_FSUTILS_PASSWD_READONLY=y
|
||||
CONFIG_NSH_CONSOLE_LOGIN=y
|
||||
|
||||
``CONFIG_FSUTILS_PASSWD`` depends on ``CONFIG_CRYPTO_CRYPTODEV``. The
|
||||
``sim:login`` defconfig also enables software cryptodev
|
||||
(``CONFIG_CRYPTO_CRYPTODEV_SOFTWARE_CRYPTO`` and ``CONFIG_CRYPTO_SW_AES``).
|
||||
|
||||
Set **Board Selection → Auto-generate /etc/passwd at build time → Root password**
|
||||
in menuconfig, in a local defconfig, or at the ``make`` prompt
|
||||
(:ref:`mkpasswd_autogen`). Only a PBKDF2-HMAC-SHA256 hash is stored in flash.
|
||||
|
||||
When ``CONFIG_NSH_LOGIN_SETUID`` is enabled (the default when
|
||||
``CONFIG_SCHED_USER_IDENTITY`` is selected), NSH looks up the
|
||||
authenticated user name in the passwd database and sets the session
|
||||
|
|
@ -90,66 +110,43 @@ will be closed. That number is controlled by::
|
|||
|
||||
CONFIG_NSH_LOGIN_FAILCOUNT=3
|
||||
|
||||
.. _nsh_login_verification:
|
||||
|
||||
Verification of Credentials
|
||||
===========================
|
||||
|
||||
There are three ways that NSH can be configured to verify user
|
||||
credentials at login time:
|
||||
There are two ways to verify credentials at login:
|
||||
|
||||
#. The simplest implementation simply uses fixed login credentials and
|
||||
is selected with::
|
||||
.. list-table:: NSH credential verification methods
|
||||
:header-rows: 1
|
||||
:widths: 20 15 65
|
||||
|
||||
CONFIG_NSH_LOGIN_FIXED=y
|
||||
* - Method
|
||||
- Kconfig
|
||||
- Summary
|
||||
* - Password file (recommended)
|
||||
- ``CONFIG_NSH_LOGIN_PASSWD=y``
|
||||
- Verifies against ``/etc/passwd`` using PBKDF2-HMAC-SHA256 hashes.
|
||||
Use with ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` for ROMFS boards.
|
||||
* - Platform callback
|
||||
- ``CONFIG_NSH_LOGIN_PLATFORM=y``
|
||||
- Board-specific ``platform_user_verify()`` function.
|
||||
|
||||
The fixed login credentials are selected via::
|
||||
When ``CONFIG_FSUTILS_PASSWD=y`` is enabled, NSH defaults to
|
||||
``CONFIG_NSH_LOGIN_PASSWD=y`` automatically. Console and telnet login
|
||||
require ``CONFIG_FSUTILS_PASSWD``; the removed fixed-login options
|
||||
``CONFIG_NSH_LOGIN_FIXED`` and ``CONFIG_NSH_LOGIN_PASSWORD`` are rejected
|
||||
at build time if still present in ``.config``.
|
||||
|
||||
CONFIG_NSH_LOGIN_USERNAME=admin
|
||||
CONFIG_NSH_LOGIN_PASSWORD="Administrator"
|
||||
|
||||
This is not very flexible since there can be only one user and the
|
||||
password is fixed in the FLASH image. This option is also not very
|
||||
secure because a malicious user could get the password by just
|
||||
looking at the ``.text`` strings in the flash image.
|
||||
|
||||
#. NSH can also be configured to defer the entire user credential
|
||||
verification to platform-specific logic with this setting::
|
||||
|
||||
CONFIG_NSH_LOGIN_PLATFORM=y
|
||||
|
||||
In this case, NSH will call a platform-specific function to perform
|
||||
the verification of user credentials. The platform-specific logic
|
||||
must provide a function with the following prototype:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
int platform_user_verify(FAR const char *username, FAR const char *password);
|
||||
|
||||
which is prototyped an described in ``apps/include/nsh.h`` and which
|
||||
may be included like:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <apps/nsh.h>
|
||||
|
||||
An appropriate place to implement this function might be in the
|
||||
directory ``apps/platform/<board>``.
|
||||
|
||||
#. A final option is to use a password file contained encrypted password
|
||||
information. This final option is selected with the following and
|
||||
described in more detail in the following paragraph::
|
||||
|
||||
CONFIG_NSH_LOGIN_PASSWD=y
|
||||
#. **Platform-specific verification.** NSH calls ``platform_user_verify()``
|
||||
when ``CONFIG_NSH_LOGIN_PLATFORM=y``. Prototype in ``apps/include/nsh.h``.
|
||||
|
||||
Password Files
|
||||
==============
|
||||
|
||||
NuttX can also be configured to support a password file, by default at
|
||||
``/etc/passwd``. This option enables support for a password file::
|
||||
|
||||
CONFIG_NSH_LOGIN_PASSWD=y
|
||||
|
||||
This options requires that you have selected ``CONFIG_FSUTILS_PASSWD=y``
|
||||
to enable the access methods of ``apps/fsutils/passwd``::
|
||||
When ``CONFIG_NSH_LOGIN_PASSWD=y`` is selected, NSH reads user names and
|
||||
password hashes from a passwd file (default ``/etc/passwd``). Enable the
|
||||
file-access layer with::
|
||||
|
||||
CONFIG_FSUTILS_PASSWD=y
|
||||
|
||||
|
|
@ -176,34 +173,127 @@ specifically disabled.
|
|||
|
||||
The password file logic requires a few additional settings:
|
||||
|
||||
#. The size of dynamically allocated and freed buffer that is used for
|
||||
#. **Kernel cryptodev**: ``CONFIG_FSUTILS_PASSWD`` requires
|
||||
``CONFIG_CRYPTO_CRYPTODEV`` (PBKDF2 via ``/dev/crypto`` at runtime).
|
||||
|
||||
#. **I/O buffer size**: size of the dynamically allocated buffer used for
|
||||
file access::
|
||||
|
||||
CONFIG_FSUTILS_PASSWD_IOBUFFER_SIZE=512
|
||||
|
||||
#. And the 128-bit encryption key. The password file currently uses the
|
||||
Tiny Encryption Algorithm (TEA), but could be extended to use
|
||||
something more powerful.
|
||||
#. **PBKDF2 iteration count**: applied when **setting** new passwords
|
||||
(via ``useradd``, ``passwd``, or build-time ``mkpasswd``)::
|
||||
|
||||
CONFIG_FSUTILS_PASSWD_KEY1=0x12345678
|
||||
CONFIG_FSUTILS_PASSWD_KEY2=0x9abcdef0
|
||||
CONFIG_FSUTILS_PASSWD_KEY3=0x12345678
|
||||
CONFIG_FSUTILS_PASSWD_KEY4=0x9abcdef0
|
||||
CONFIG_FSUTILS_PASSWD_PBKDF2_ITERATIONS=10000
|
||||
|
||||
Password can only be decrypted with access to this key. Note that this
|
||||
key could potentially be fished out of your FLASH image, but without any
|
||||
symbolic information, that would be a difficult job since the TEA KEY is
|
||||
binary data and not distinguishable from other binary data in the FLASH
|
||||
image.
|
||||
Valid range: 1000 to 200000. Higher values resist brute-force attacks
|
||||
but increase login latency on low-MHz MCUs. The iteration count is
|
||||
stored inside each hash string, so changing this option only affects
|
||||
newly-created passwords.
|
||||
|
||||
If the password file is enabled (``CONFIG_NSH_LOGIN_PASSWD=y``), then
|
||||
the fixed user credentials will not be used for the NSH session login.
|
||||
Instead, the password file will be consulted to verify the user
|
||||
credentials.
|
||||
#. **Random salt source**: new salts require random bytes. Enable a
|
||||
platform random source such as::
|
||||
|
||||
CONFIG_DEV_URANDOM=y
|
||||
|
||||
``passwd_encrypt()`` uses ``getrandom()`` or ``/dev/urandom`` when
|
||||
generating salts for ``useradd`` and ``passwd``.
|
||||
|
||||
Password complexity rules
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The same rules are enforced everywhere a **new** password is set:
|
||||
|
||||
* Build-time ``tools/mkpasswd`` (ROMFS autogen)
|
||||
* NSH commands ``useradd`` and ``passwd``
|
||||
* Runtime API ``passwd_encrypt()`` in ``apps/fsutils/passwd``
|
||||
|
||||
Rules:
|
||||
|
||||
* At least **8** characters
|
||||
* At least one **uppercase** letter (``A`` to ``Z``)
|
||||
* At least one **lowercase** letter (``a`` to ``z``)
|
||||
* At least one **digit** (``0`` to ``9``)
|
||||
* At least one **special** character from::
|
||||
|
||||
! @ # $ % ^ & * ( ) _ + - = [ ] { } | ; : , . < > ?
|
||||
|
||||
If ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` is missing or does not meet
|
||||
these rules, an interactive ``make`` prompts via ``tools/promptpasswd.sh``
|
||||
(root password, then confirm password). Non-interactive builds must set the
|
||||
password in menuconfig or export ``NUTTX_ROMFS_PASSWD_PASSWORD`` first.
|
||||
|
||||
Password hash format
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Each password field uses **PBKDF2-HMAC-SHA256** in modular crypt format
|
||||
(MCF). The hash string is self-contained: it stores the iteration count
|
||||
and salt, so verification does not depend on separate key material in
|
||||
firmware::
|
||||
|
||||
$pbkdf2-sha256$<iterations>$<base64url-salt>$<base64url-hash>
|
||||
|
||||
Where:
|
||||
|
||||
* ``<iterations>``: PBKDF2 round count (parsed at verify time)
|
||||
* ``<base64url-salt>``: 16-byte random salt (RFC 4648 section 5, no padding)
|
||||
* ``<base64url-hash>``: 32-byte PBKDF2-HMAC-SHA256 output (same encoding)
|
||||
|
||||
Example ``/etc/passwd`` line::
|
||||
|
||||
root:$pbkdf2-sha256$10000$zhoo4phwEzyNFUAkB7asfw$P8qsjd9RQmZBLfM5zugiJeE5gKjI-CmTxyaVyOX2mE4:0:0:/
|
||||
|
||||
Full ``/etc/passwd`` record format::
|
||||
|
||||
user:hash:uid:gid:home
|
||||
|
||||
.. note::
|
||||
|
||||
**Breaking change:** this replaces the former TEA-based password storage.
|
||||
Existing TEA-encoded entries will **not** verify. Regenerate every entry
|
||||
with ``mkpasswd``, NSH ``passwd``, or ``useradd`` after upgrading.
|
||||
|
||||
``passwd_verify()`` returns ``0`` on match, ``-1`` on mismatch or invalid
|
||||
hash format, and a negated ``errno`` on I/O errors.
|
||||
|
||||
When ``CONFIG_NSH_LOGIN_PASSWD=y`` is enabled, NSH verifies logins against
|
||||
the password file rather than compile-time credentials.
|
||||
|
||||
Notes on ``savedefconfig``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To avoid leaking credentials into board defconfigs, ``make savedefconfig``
|
||||
**omits** these options from the generated defconfig:
|
||||
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``
|
||||
* ``CONFIG_FSUTILS_PASSWD_PBKDF2_ITERATIONS``
|
||||
|
||||
Add them manually to a local defconfig after ``make savedefconfig`` if
|
||||
needed for development.
|
||||
|
||||
Creating a Password File for a ROMFS File System
|
||||
================================================
|
||||
|
||||
Boards with ``CONFIG_ETC_ROMFS`` can auto-generate ``/etc/passwd`` at
|
||||
**build time** when ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``.
|
||||
|
||||
Build-time flow
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
1. You configure the root password in menuconfig, at the interactive
|
||||
``make`` prompt, or via ``NUTTX_ROMFS_PASSWD_PASSWORD``.
|
||||
2. The build runs ``tools/mkpasswd`` (Makefile builds use
|
||||
``tools/board_romfs_mkpasswd.sh`` as a wrapper).
|
||||
3. Only the **hash** is written into the ROMFS image at ``/etc/passwd``.
|
||||
4. At boot, NSH login verifies the password through kernel cryptodev
|
||||
(``/dev/crypto``).
|
||||
|
||||
See :ref:`mkpasswd_autogen` in :doc:`/components/tools/index` for the full
|
||||
tool description, Kconfig list, and verification steps.
|
||||
|
||||
The following describes the **manual** approach for creating or updating a
|
||||
password file when build-time autogen is **not** used.
|
||||
|
||||
What we want to accomplish is a ROMFS file system, mounted at ``/etc``
|
||||
and containing the password file, ``passwd`` like::
|
||||
|
||||
|
|
@ -220,10 +310,10 @@ and containing the password file, ``passwd`` like::
|
|||
nsh>
|
||||
|
||||
Where ``/etc/init.d/rc.sysinit`` is the system init script and
|
||||
``/etc/init.d/rcS`` is the start-up script; ``/etc/passwd`` is a
|
||||
the password file. Note that here we assume that you are already using a
|
||||
``/etc/init.d/rcS`` is the start-up script; ``/etc/passwd`` is the
|
||||
password file. Note that here we assume that you are already using a
|
||||
start-up script. We can then piggyback the passwd file into the ``/etc``
|
||||
file system already mounted for the NSH start up file as described above
|
||||
file system already mounted for the NSH start up file as described
|
||||
`above <#custinit>`__.
|
||||
|
||||
The sim/nsh configuration can be used to create a new password file, but other
|
||||
|
|
@ -267,7 +357,7 @@ new user passwords like::
|
|||
nsh> useradd <username> <password>
|
||||
|
||||
Do this as many times as you would like. Each time that you do this a
|
||||
new entry with an encrypted password will be added to the ``passwd``
|
||||
new entry with a hashed password will be added to the ``passwd``
|
||||
file at ``/tmp/passwd``. You can see the content of the password file
|
||||
like::
|
||||
|
||||
|
|
@ -286,9 +376,10 @@ Then create/re-create the ``nsh_romfsimg.h`` file as described below.
|
|||
mkdir etc
|
||||
mkdir etc/init.d
|
||||
|
||||
And copy your existing startup script into ``etc/init.c`` as ``rcS``.
|
||||
And copy your existing startup script into ``etc/init.d/`` as ``rcS``.
|
||||
|
||||
#. Save your new password file in the ``etc/`` directory as ``passwd``.
|
||||
Each line must use the PBKDF2 MCF format described above.
|
||||
|
||||
#. Create the new ROMFS image::
|
||||
|
||||
|
|
@ -298,12 +389,9 @@ Then create/re-create the ``nsh_romfsimg.h`` file as described below.
|
|||
|
||||
xxd -i romfs_img >nsh_romfsimg.h
|
||||
|
||||
#. Edit ``nsh_romfsimg.h``: Mark both data definitions as ``const`` so
|
||||
#. Edit ``nsh_romfsimg.h``: mark both data definitions as ``const`` so
|
||||
that the data will be stored in FLASH.
|
||||
|
||||
#. Edit nsh_romfsimg.h, mark both data definitions as ``const`` so that
|
||||
that will be stored in FLASH.
|
||||
|
||||
There is a good example of how to do this in the NSH simulation
|
||||
configuration at
|
||||
`boards/sim/sim/sim/configs/nsh <https://github.com/apache/nuttx/blob/master/boards/sim/sim/sim/configs/nsh/>`__.
|
||||
|
|
|
|||
|
|
@ -14,60 +14,55 @@ and host C programs that are important parts of the NuttX build system:
|
|||
|
||||
.. _mkpasswd_autogen:
|
||||
|
||||
mkpasswd — Build-time ``/etc/passwd`` Generation
|
||||
-------------------------------------------------
|
||||
mkpasswd: Build-time ``/etc/passwd`` generation
|
||||
===============================================
|
||||
|
||||
``tools/mkpasswd`` (``tools/mkpasswd.c``) is a host program that writes a
|
||||
single ``/etc/passwd`` entry with a TEA-encrypted password hash. The
|
||||
plaintext password is **not** stored in the firmware image.
|
||||
``tools/mkpasswd`` (``tools/mkpasswd.c``) writes one ``/etc/passwd`` line at
|
||||
build time when ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``.
|
||||
|
||||
When ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``, the build invokes
|
||||
``mkpasswd`` automatically from ``boards/Board.mk`` (Make) or
|
||||
``cmake/nuttx_add_romfs.cmake`` (CMake). You normally configure the
|
||||
password and keys in menuconfig; you do not run ``mkpasswd`` by hand.
|
||||
Quick start
|
||||
~~~~~~~~~~~
|
||||
|
||||
Prerequisites
|
||||
~~~~~~~~~~~~~
|
||||
.. code:: kconfig
|
||||
|
||||
Enable all of the following (via ``make menuconfig``):
|
||||
CONFIG_ETC_ROMFS=y
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
|
||||
CONFIG_FSUTILS_PASSWD=y
|
||||
CONFIG_FSUTILS_PASSWD_READONLY=y
|
||||
CONFIG_NSH_CONSOLE_LOGIN=y
|
||||
|
||||
* **Board Selection** → **Auto-generate /etc/passwd at build time**
|
||||
(``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE``)
|
||||
* **Application Configuration** → **NSH Library** → **Console Login**
|
||||
(``CONFIG_NSH_CONSOLE_LOGIN``) with verification method **Encrypted
|
||||
password file** (``CONFIG_NSH_LOGIN_PASSWD``)
|
||||
* **Application Configuration** → **File System Utilities** → **Password file
|
||||
support** (``CONFIG_FSUTILS_PASSWD``)
|
||||
Set **Board Selection → Auto-generate /etc/passwd at build time → Root password**
|
||||
in menuconfig or at the ``make`` prompt, then build and log in as ``root``.
|
||||
|
||||
Setup workflow
|
||||
~~~~~~~~~~~~~~
|
||||
See :doc:`/applications/nsh/login` for NSH login details.
|
||||
|
||||
1. ``tools/configure.sh <board>:<config>``
|
||||
2. ``make menuconfig``:
|
||||
Build flow
|
||||
~~~~~~~~~~
|
||||
|
||||
* **Board Selection** → Auto-generate /etc/passwd
|
||||
**Makefile builds** use ``tools/board_romfs_mkpasswd.sh``, which validates the
|
||||
password (``tools/promptpasswd.sh`` if needed) and invokes ``tools/mkpasswd``.
|
||||
|
||||
* **Admin password** — required, at least 8 characters. There is no
|
||||
Kconfig default (the legacy ``Administrator`` password is rejected).
|
||||
* **Generate random TEA encryption keys automatically** — recommended;
|
||||
or disable this and set keys manually (see below).
|
||||
**CMake builds** invoke ``tools/mkpasswd`` directly; set
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` in ``.config`` (configure fails if
|
||||
it is missing).
|
||||
|
||||
* Confirm NSH uses **Encrypted password file** verification (above).
|
||||
In both cases:
|
||||
|
||||
3. ``make`` — on the first build, ``tools/passwd_keys.mk`` validates the
|
||||
password and keys, may generate TEA keys, then ``mkpasswd`` runs before
|
||||
``config.h`` is created so the hash and firmware always agree.
|
||||
1. ``tools/mkpasswd`` hashes with PBKDF2-HMAC-SHA256 (same algorithm as
|
||||
``apps/fsutils/passwd``, which uses kernel cryptodev at runtime).
|
||||
2. The hash is written to ``etctmp/.../passwd`` and embedded in ROMFS.
|
||||
|
||||
The plaintext password is used on the host during ``make`` only. On an
|
||||
interactive terminal, ``make`` prompts for the root password (and confirmation)
|
||||
when it is not already configured; non-interactive builds must set
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` or ``NUTTX_ROMFS_PASSWD_PASSWORD``.
|
||||
|
||||
Build-time credentials (CI / automation)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These values are **not** written to defconfig by ``make savedefconfig``:
|
||||
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD``
|
||||
* ``CONFIG_FSUTILS_PASSWD_KEY1`` … ``CONFIG_FSUTILS_PASSWD_KEY4``
|
||||
|
||||
For scripted or CI builds, export the admin password before ``configure.sh``
|
||||
or ``make``:
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` is **not** written to defconfig by
|
||||
``make savedefconfig``. For scripted or CI builds, export the root password
|
||||
before ``configure.sh`` or ``make``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
|
@ -75,83 +70,48 @@ or ``make``:
|
|||
|
||||
``tools/update_romfs_password.sh`` copies this into ``.config`` when ROMFS
|
||||
passwd generation is enabled and the password field is still empty. NuttX
|
||||
CI sets ``NuttXSimLogin1`` for the ``sim/login`` configuration (a documented
|
||||
sim-only test credential, not a product secret).
|
||||
CI sets ``NuttXSim1!`` for the ``sim/login`` configuration (a documented
|
||||
sim-only test credential, not a product secret). The password must meet the
|
||||
complexity rules below.
|
||||
|
||||
TEA encryption keys
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
Password rules
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
``mkpasswd`` and the firmware must use the **same** four 32-bit key words
|
||||
(``CONFIG_FSUTILS_PASSWD_KEY1`` … ``KEY4``). Choose one approach:
|
||||
Minimum 8 characters; at least one uppercase, lowercase, digit, and special
|
||||
character from ``!@#$%^&*()_+-=[]{}|;:,.<>?``.
|
||||
|
||||
**Random generation** (``CONFIG_BOARD_ETC_ROMFS_PASSWD_RANDOMIZE_KEYS=y``):
|
||||
Hash format
|
||||
~~~~~~~~~~~
|
||||
|
||||
On the first ``make`` when keys are missing or still placeholders,
|
||||
``tools/gen_passwd_keys.sh`` writes random values to ``.config``. A
|
||||
build warning explains where to view or change them in menuconfig. Key
|
||||
values are never printed in the build log.
|
||||
::
|
||||
|
||||
**Manual keys** (``CONFIG_BOARD_ETC_ROMFS_PASSWD_RANDOMIZE_KEYS`` disabled):
|
||||
$pbkdf2-sha256$<iterations>$<base64url-salt>$<base64url-hash>
|
||||
|
||||
Set ``CONFIG_FSUTILS_PASSWD_KEY1`` … ``KEY4`` under **Application
|
||||
Configuration** → **File System Utilities** → **Password file support**.
|
||||
Each must be a unique non-zero value. The legacy published defaults
|
||||
``0x12345678`` / ``0x9abcdef0`` are rejected.
|
||||
Example::
|
||||
|
||||
If random generation is enabled but keys are already present in ``.config``,
|
||||
they are **not** regenerated (subsequent builds stay consistent).
|
||||
root:$pbkdf2-sha256$10000$zhoo4phwEzyNFUAkB7asfw$P8qsjd9RQmZBLfM5zugiJeE5gKjI-CmTxyaVyOX2mE4
|
||||
|
||||
How the build enforces security
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
**Breaking change:** TEA-encoded entries are not compatible. Regenerate with
|
||||
``mkpasswd`` or NSH ``passwd`` / ``useradd``.
|
||||
|
||||
+---------------------------+-----------------------------------------------+
|
||||
| Check | Where |
|
||||
+===========================+===============================================+
|
||||
| Password set, min 8 chars | ``tools/passwd_keys.mk`` (before ``config.h``)|
|
||||
| Not ``Administrator`` | ``tools/mkpasswd.c`` (last line of defence) |
|
||||
| TEA keys configured | ``tools/check_passwd_keys.sh`` |
|
||||
| Not legacy default keys | ``check_passwd_keys.sh`` + ``mkpasswd.c`` |
|
||||
+---------------------------+-----------------------------------------------+
|
||||
|
||||
Standalone ``mkpasswd`` (advanced)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For debugging only, you may run the host binary directly. You must pass all
|
||||
four ``--key`` options with non-default values and a password of at least 8
|
||||
characters:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
./tools/mkpasswd --user root --password 'my-secret' \
|
||||
--key1 0x11111111 --key2 0x22222222 \
|
||||
--key3 0x33333333 --key4 0x44444444
|
||||
|
||||
Kconfig summary
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Example ``.config`` fragment (password and keys normally **not** in defconfig):
|
||||
Kconfig
|
||||
~~~~~~~
|
||||
|
||||
.. code:: kconfig
|
||||
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_RANDOMIZE_KEYS=y
|
||||
CONFIG_CRYPTO_CRYPTODEV=y
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_USER="root"
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD="<set in menuconfig or env>"
|
||||
CONFIG_NSH_CONSOLE_LOGIN=y
|
||||
CONFIG_NSH_LOGIN_PASSWD=y
|
||||
CONFIG_FSUTILS_PASSWD=y
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD="<secret>"
|
||||
CONFIG_FSUTILS_PASSWD_PBKDF2_ITERATIONS=10000
|
||||
|
||||
``/etc/passwd`` file format
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
``make savedefconfig`` omits ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` and
|
||||
``CONFIG_FSUTILS_PASSWD_PBKDF2_ITERATIONS`` to avoid leaking credentials.
|
||||
|
||||
.. code:: text
|
||||
Host files
|
||||
~~~~~~~~~~
|
||||
|
||||
user:encrypted_hash:uid:gid:home
|
||||
|
||||
Notes on ``savedefconfig``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``make savedefconfig`` omits the password and ``KEY1``–``KEY4`` from the
|
||||
generated defconfig on purpose. ``CONFIG_BOARD_ETC_ROMFS_PASSWD_RANDOMIZE_KEYS``
|
||||
may remain in defconfig (policy, not a secret). Do not commit passwords or
|
||||
key values to version control.
|
||||
* ``tools/mkpasswd.c`` - PBKDF2 hash generation
|
||||
* ``tools/promptpasswd.sh`` - interactive root password prompt, validation,
|
||||
and confirmation
|
||||
* ``tools/board_romfs_mkpasswd.sh`` - Makefile ROMFS build wrapper
|
||||
|
|
|
|||
|
|
@ -2,3 +2,27 @@
|
|||
moxa
|
||||
====
|
||||
|
||||
Configurations
|
||||
==============
|
||||
|
||||
nsh
|
||||
---
|
||||
|
||||
This configuration enables NSH with Telnet and telnet login. Credentials
|
||||
are verified against a PBKDF2-HMAC-SHA256 hash in ROMFS ``/etc/passwd``, not
|
||||
a fixed plaintext password compiled into the firmware.
|
||||
|
||||
Before building:
|
||||
|
||||
1. ``./tools/configure.sh moxa:nsh``
|
||||
2. Set the root password in menuconfig (**Board Selection** →
|
||||
**Auto-generate /etc/passwd at build time** → **Root password**), or
|
||||
export ``NUTTX_ROMFS_PASSWD_PASSWORD`` before ``make``.
|
||||
|
||||
The former fixed telnet password ``nuttx`` is no longer embedded in the
|
||||
image. For a local test build you may use (must meet complexity rules)::
|
||||
|
||||
export NUTTX_ROMFS_PASSWD_PASSWORD='NuttX1!nut'
|
||||
make
|
||||
|
||||
See :ref:`mkpasswd_autogen` for details.
|
||||
|
|
|
|||
|
|
@ -495,34 +495,39 @@ start-up script; ``/etc/passwd`` is the password file.
|
|||
|
||||
The ``/etc/passwd`` file is auto-generated at build time when
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set. See :ref:`mkpasswd_autogen`
|
||||
for the full setup (admin password, TEA keys, NSH encrypted-password login).
|
||||
for the full setup (root password, NSH encrypted-password login).
|
||||
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``root``)
|
||||
* Admin password and TEA keys — set in menuconfig (not saved in defconfig)
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required; minimum 8 characters
|
||||
with uppercase, lowercase, digit, and special character. See
|
||||
:ref:`mkpasswd_autogen`)
|
||||
|
||||
The password is hashed with TEA by ``tools/mkpasswd``; the plaintext is **not**
|
||||
stored in the firmware.
|
||||
The password is hashed with PBKDF2-HMAC-SHA256 at build time by the host tool
|
||||
``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
|
||||
|
||||
For the full description of the mechanism, file format, and verification
|
||||
steps, see :ref:`mkpasswd_autogen`.
|
||||
|
||||
The format of the password file is:
|
||||
|
||||
.. code:: text
|
||||
|
||||
user:encrypted_hash:uid:gid:home
|
||||
user:x:uid:gid:home
|
||||
|
||||
Where:
|
||||
user: User name
|
||||
encrypted_hash: TEA-encrypted password (base64)
|
||||
uid: User ID
|
||||
gid: Group ID
|
||||
home: Login directory
|
||||
x: PBKDF2-HMAC-SHA256 hash (modular crypt format)
|
||||
uid: User ID (0 for now)
|
||||
gid: Group ID (0 for now)
|
||||
home: Login directory (/ for now)
|
||||
|
||||
``/etc/group`` is a group file. It is not currently used.
|
||||
|
||||
.. code:: console
|
||||
|
||||
nsh> cat /etc/group
|
||||
root:*:0:root,admin
|
||||
root:*:0:root
|
||||
|
||||
The format of the group file is:
|
||||
|
||||
|
|
|
|||
|
|
@ -31,13 +31,16 @@ README
|
|||
|
||||
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)
|
||||
CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD (required; minimum 8 characters
|
||||
with uppercase, lowercase, digit, and special character)
|
||||
|
||||
The password is hashed with TEA at build time by the host tool
|
||||
The password is hashed with PBKDF2-HMAC-SHA256 at build time by the host tool
|
||||
tools/mkpasswd; the plaintext is NOT stored in the firmware image.
|
||||
If the password is not set in .config, an interactive make prompts via
|
||||
tools/promptpasswd.sh (root password, then confirm password).
|
||||
|
||||
For the full description of the mechanism, TEA key configuration, file
|
||||
format, and verification steps, see Documentation/components/tools/index.rst
|
||||
For the full description of the mechanism, file format, complexity rules,
|
||||
and verification steps, see Documentation/components/tools/index.rst
|
||||
(mkpasswd section).
|
||||
|
||||
The format of the password file is:
|
||||
|
|
@ -46,7 +49,7 @@ README
|
|||
|
||||
Where:
|
||||
user: User name
|
||||
x: Encrypted password
|
||||
x: PBKDF2-HMAC-SHA256 hash (modular crypt format)
|
||||
uid: User ID (0 for now)
|
||||
gid: Group ID (0 for now)
|
||||
home: Login directory (/ for now)
|
||||
|
|
@ -54,7 +57,7 @@ README
|
|||
/etc/group is a group file. It is not currently used.
|
||||
|
||||
nsh> cat /etc/group
|
||||
root:*:0:root,admin
|
||||
root:*:0:root
|
||||
|
||||
The format of the group file is:
|
||||
|
||||
|
|
|
|||
|
|
@ -1996,15 +1996,17 @@ This is a configuration with login password protection for NSH.
|
|||
.. note::
|
||||
|
||||
This config has password protection enabled. After configuring from
|
||||
defconfig, set the admin password in menuconfig (Board Selection →
|
||||
defconfig, set the root password in menuconfig (Board Selection →
|
||||
Auto-generate /etc/passwd) or export ``NUTTX_ROMFS_PASSWD_PASSWORD``
|
||||
before building. NuttX CI uses the documented test password
|
||||
``NuttXSimLogin1`` for this configuration.
|
||||
``NuttXSim1!`` for this configuration.
|
||||
|
||||
* USERNAME: root (default)
|
||||
* PASSWORD: set at build time (not stored in defconfig)
|
||||
|
||||
The encrypted password is retained in ``/etc/passwd``.
|
||||
The password must meet complexity rules (8+ chars, upper, lower, digit,
|
||||
special). Only the PBKDF2-HMAC-SHA256 hash is stored in ``/etc/passwd``.
|
||||
|
||||
You can disable the password protection by
|
||||
de-selecting ``CONFIG_NSH_CONSOLE_LOGIN=y``.
|
||||
|
||||
|
|
@ -2205,29 +2207,46 @@ mounted at ``/etc`` and will look like this at run-time:
|
|||
start-up script; ``/etc/passwd`` is the password file.
|
||||
|
||||
The ``/etc/passwd`` file is auto-generated at build time when
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set. Configure credentials in
|
||||
``make menuconfig`` (see :ref:`mkpasswd_autogen`):
|
||||
``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE`` is set. Enable the option and set
|
||||
credentials via ``make menuconfig``:
|
||||
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y``
|
||||
* ``CONFIG_NSH_CONSOLE_LOGIN=y`` with **Encrypted password file** verification
|
||||
* ``CONFIG_NSH_CONSOLE_LOGIN=y`` (required, otherwise login is not enforced)
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_USER`` (default: ``root``)
|
||||
* Admin password — required in menuconfig or via ``NUTTX_ROMFS_PASSWD_PASSWORD``
|
||||
(minimum 8 characters; not saved in defconfig)
|
||||
* TEA keys — enable **Generate random TEA encryption keys automatically**, or
|
||||
set ``CONFIG_FSUTILS_PASSWD_KEY1`` … ``KEY4`` manually
|
||||
* ``CONFIG_BOARD_ETC_ROMFS_PASSWD_PASSWORD`` (required; minimum 8 characters
|
||||
with uppercase, lowercase, digit, and special character. See
|
||||
:ref:`mkpasswd_autogen`)
|
||||
|
||||
The password is hashed with TEA by ``tools/mkpasswd``; the plaintext is **not**
|
||||
stored in the firmware.
|
||||
The password is hashed with PBKDF2-HMAC-SHA256 at build time by the host tool
|
||||
``tools/mkpasswd``; the plaintext is **not** stored in the firmware.
|
||||
|
||||
For the full build flow, CI credentials, and verification steps, see
|
||||
For the full description of the build-time password generation mechanism,
|
||||
file format, and verification steps, see
|
||||
:ref:`mkpasswd_autogen`.
|
||||
|
||||
The format of the password file is:
|
||||
|
||||
.. code:: text
|
||||
|
||||
user:x:uid:gid:home
|
||||
|
||||
Where:
|
||||
|
||||
* user: User name
|
||||
* x: PBKDF2-HMAC-SHA256 hash (modular crypt format)
|
||||
* uid: User ID (0 for now)
|
||||
* gid: Group ID (0 for now)
|
||||
* home: Login directory (/ for now)
|
||||
|
||||
For configuration, verification steps, and password complexity rules, see
|
||||
:ref:`mkpasswd_autogen`.
|
||||
|
||||
Login test inside the simulator
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use the admin password you set at build time (menuconfig or
|
||||
Use the root password you set at build time (menuconfig or
|
||||
``NUTTX_ROMFS_PASSWD_PASSWORD``). For ``sim/login``, CI uses the documented
|
||||
test password ``NuttXSimLogin1``; see :ref:`mkpasswd_autogen`.
|
||||
test password ``NuttXSim1!``; see :ref:`mkpasswd_autogen`.
|
||||
|
||||
.. code:: console
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue