This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit d487c46a292d96bee1bb59b229c84714865bd40c Author: Abhishek Mishra <[email protected]> AuthorDate: Thu Jun 11 19:48:15 2026 +0000 Documentation/sched: Add POSIX user identity transition docs Adds comprehensive documentation for the POSIX three-tier user identity model (real, effective, saved-set IDs) enabled by CONFIG_SCHED_USER_IDENTITY. * Updates sched/Kconfig with detailed help text explaining the config. * Adds user_identity.rst to formally document credential inheritance and the privilege transition rules for setuid(), seteuid(), setgid(), and setegid(). * Updates tasks_vs_threads.rst to list credentials as a shared task group resource. Signed-off-by: Abhishek Mishra <[email protected]> --- Documentation/implementation/index.rst | 1 + Documentation/implementation/tasks_vs_threads.rst | 2 + Documentation/implementation/user_identity.rst | 71 +++++++++++++++++++++++ include/nuttx/sched.h | 8 +-- sched/Kconfig | 19 ++++-- 5 files changed, 91 insertions(+), 10 deletions(-) diff --git a/Documentation/implementation/index.rst b/Documentation/implementation/index.rst index b05cffad841..bcb87e9eff3 100644 --- a/Documentation/implementation/index.rst +++ b/Documentation/implementation/index.rst @@ -38,4 +38,5 @@ Implementation Details tasks_vs_threads.rst tickless_os.rst tls.rst + user_identity.rst usb.rst diff --git a/Documentation/implementation/tasks_vs_threads.rst b/Documentation/implementation/tasks_vs_threads.rst index 4bd14efb6f4..71bd38f989c 100644 --- a/Documentation/implementation/tasks_vs_threads.rst +++ b/Documentation/implementation/tasks_vs_threads.rst @@ -69,6 +69,8 @@ reside within the task group structure struct ``task_group_s``: * Opened message queues. * ``pthread`` keys. * Support data for ``atexit()``, ``on_exit()``, and/or ``waitpid()``. +* User and group identity when ``CONFIG_SCHED_USER_IDENTITY`` is enabled + (see :ref:`user-identity`). The exception is the PIC address space used with NXFLAT. It currently has its own data structure (struct ``dspace_s``, diff --git a/Documentation/implementation/user_identity.rst b/Documentation/implementation/user_identity.rst new file mode 100644 index 00000000000..ab7ecdaa6ca --- /dev/null +++ b/Documentation/implementation/user_identity.rst @@ -0,0 +1,71 @@ +.. _user-identity: + +======================= +User and Group Identity +======================= + +When ``CONFIG_SCHED_USER_IDENTITY`` is enabled, each task group maintains POSIX +process credentials. All threads within a task group share the same credentials +(see :ref:`tasks-vs-threads`). + +Credentials +=========== + +The full POSIX three-field credential model is stored in ``struct task_group_s`` +(``include/nuttx/sched.h``): + +* ``tg_uid`` / ``tg_gid`` — real user and group IDs. +* ``tg_euid`` / ``tg_egid`` — effective IDs used for permission checks. +* ``tg_suid`` / ``tg_sgid`` — saved set-IDs that allow a non-root process to + restore a previously held effective ID. + +All six fields are zero-initialized at task creation, so the initial task runs +as root (UID/GID 0) unless explicitly changed. + +Inheritance +=========== + +When a new task is created, ``group_inherit_identity()`` in +``sched/group/group_create.c`` copies all six credential fields from the parent +task group to the child task group. + +Privilege Transitions +===================== + +``setuid()`` and ``setgid()`` +----------------------------- + +When the effective ID is zero (root): + +* ``setuid(uid)`` sets ``tg_uid``, ``tg_euid``, and ``tg_suid`` to ``uid``. +* ``setgid(gid)`` sets ``tg_gid``, ``tg_egid``, and ``tg_sgid`` to ``gid``. + +When the effective ID is non-zero: + +* The caller may only set the effective ID to the current real or saved value. +* Any other value causes the function to return ``-1`` with ``errno`` set to + ``EPERM``. + +``seteuid()`` and ``setegid()`` +------------------------------- + +When the effective ID is zero, any value may be assigned as the new effective +ID. + +When the effective ID is non-zero, the requested value must equal the real or +the saved ID. Otherwise the function returns ``-1`` with ``errno`` set to +``EPERM``. + +This implements the standard POSIX pattern of temporarily dropping privileges +with ``seteuid()`` or ``setegid()`` and later restoring them to the saved value. + +Configuration +============= + +``CONFIG_SCHED_USER_IDENTITY`` + Enables per-task-group credential tracking. Without this option, stub + root-only versions of all credential interfaces are provided. + +``CONFIG_FS_PERMISSION`` + Enables filesystem ownership and permission enforcement. Requires + ``CONFIG_SCHED_USER_IDENTITY``. diff --git a/include/nuttx/sched.h b/include/nuttx/sched.h index ca3781995bd..9f40db43828 100644 --- a/include/nuttx/sched.h +++ b/include/nuttx/sched.h @@ -455,13 +455,13 @@ struct task_group_s pid_t tg_ppid; /* This is the ID of the parent thread */ uint8_t tg_flags; /* See GROUP_FLAG_* definitions */ - /* User identity **********************************************************/ + /* User identity (POSIX real, effective, and saved-set IDs) ***************/ #ifdef CONFIG_SCHED_USER_IDENTITY - uid_t tg_uid; /* User identity */ - gid_t tg_gid; /* User group identity */ + uid_t tg_uid; /* Real user identity */ + gid_t tg_gid; /* Real group identity */ uid_t tg_euid; /* Effective user identity */ - gid_t tg_egid; /* Effective user group identity */ + gid_t tg_egid; /* Effective group identity */ uid_t tg_suid; /* Saved set-user identity */ gid_t tg_sgid; /* Saved set-group identity */ #endif diff --git a/sched/Kconfig b/sched/Kconfig index 9b4ed4c82c8..3b5808a4417 100644 --- a/sched/Kconfig +++ b/sched/Kconfig @@ -789,12 +789,19 @@ config SCHED_USER_IDENTITY bool "Support per-task User Identity" default n ---help--- - This selection enables functionality of getuid(), setuid(), getgid(), - setgid(). If this option is not selected, then stub, root-only - versions of these interfaces are available. When selected, these - interfaces will associate a UID and/or GID with each task group. - Those can then be managed using the interfaces. Child tasks will - inherit the UID and GID of its parent. + Enable per-task-group POSIX user and group credentials. + + When selected, each task group tracks real, effective, and saved-set + UID/GID values and provides getuid(), getgid(), geteuid(), + getegid(), setuid(), setgid(), seteuid(), and setegid(). + + Child tasks inherit all credential fields from the parent task + group. setuid()/setgid() update real, effective, and saved-set + IDs when called with effective privileges; seteuid()/setegid() + implement the standard POSIX privilege transition rules. + + If this option is not selected, stub root-only versions of these + interfaces are available instead. config SCHED_THREAD_LOCAL bool "Support __thread/thread_local keyword"
