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 <mishra.abhishek2808@gmail.com>

Documentation/implementation/index.rst

@@ -38,4 +38,5 @@ Implementation Details
    tasks_vs_threads.rst
    tickless_os.rst
    tls.rst
+   user_identity.rst
    usb.rst

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``,

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``.

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

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"