git: b6f4027ad9a2 - main - setcred(2): Add manual page

The branch main has been updated by olce:

URL: https://cgit.FreeBSD.org/src/commit/?id=b6f4027ad9a2ede69a7ec11137cc4ea69ec2f0a0

commit b6f4027ad9a2ede69a7ec11137cc4ea69ec2f0a0
Author:     Olivier Certner <olce@FreeBSD.org>
AuthorDate: 2024-12-12 08:38:00 +0000
Commit:     Olivier Certner <olce@FreeBSD.org>
CommitDate: 2024-12-19 22:36:00 +0000

    setcred(2): Add manual page
    
    Reviewed by:    Alexander Ziaee <concussious@runbox.com>
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D48063
---
 lib/libsys/Makefile.sys |   1 +
 lib/libsys/setcred.2    | 290 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 291 insertions(+)

diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys
index 04e767d50f86..29c40eb334ba 100644
--- a/lib/libsys/Makefile.sys
+++ b/lib/libsys/Makefile.sys
@@ -311,6 +311,7 @@ MAN+=	abort2.2 \
 	semget.2 \
 	semop.2 \
 	send.2 \
+	setcred.2 \
 	setfib.2 \
 	sendfile.2 \
 	setgroups.2 \
diff --git a/lib/libsys/setcred.2 b/lib/libsys/setcred.2
new file mode 100644
index 000000000000..a1b819d24c52
--- /dev/null
+++ b/lib/libsys/setcred.2
@@ -0,0 +1,290 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright © 2024 The FreeBSD Foundation
+.\"
+.\" This documentation was written by Olivier Certner <olce.freebsd@certner.fr>
+.\" at Kumacom SARL under sponsorship from the FreeBSD Foundation.
+.\"
+.Dd December 19, 2024
+.Dt SETCRED 2
+.Os
+.Sh NAME
+.Nm setcred
+.Nd set current process credentials atomically
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/ucred.h
+.Ft int
+.Fn setcred "u_int flags" "const struct setcred *wcred" "size_t size"
+.Sh DESCRIPTION
+The
+.Fn setcred
+system call can set any combination of user-accessible credentials of the
+current process in an atomic manner.
+.Pp
+This system call is normally permitted only for processes having the ID of the
+super-user (0) as their effective user ID, or not at all if the
+.Xr sysctl 8
+variable
+.Va security.bsd.suser_enabled
+is zero or some active MAC policy specifically denies these processes.
+.Pp
+Some MAC policies, such as
+.Xr mac_do 4 ,
+may also allow unprivileged users to call it successfully, possibly depending on
+the exact credentials transition requested, once again unless any active MAC
+policy specifically denies that.
+.Pp
+The
+.Fa flags
+argument serves to indicate which process credentials should be changed by the
+call.
+Allowed flags are:
+.Pp
+.Bl -tag -width "SETCREDF_SUPP_GROUPS   " -compact
+.It Fa SETCREDF_UID
+Set the effective user ID.
+.It Fa SETCREDF_RUID
+Set the real user ID.
+.It Fa SETCREDF_SVUID
+Set the saved user ID.
+.It Fa SETCREDF_GID
+Set the effective group ID.
+.It Fa SETCREDF_RGID
+Set the real group ID.
+.It Fa SETCREDF_SVGID
+Set the saved group ID.
+.It Fa SETCREDF_SUPP_GROUPS
+Set the supplementary group list.
+.It Fa SETCREDF_MAC_LABEL
+Set the MAC label.
+.El
+.Pp
+The
+.Vt struct setcred
+structure is currently defined as:
+.Bd -literal
+struct setcred {
+	uid_t	 sc_uid;		/* effective user id */
+	uid_t	 sc_ruid;		/* real user id */
+	uid_t	 sc_svuid;		/* saved user id */
+	gid_t	 sc_gid;		/* effective group id */
+	gid_t	 sc_rgid;		/* real group id */
+	gid_t	 sc_svgid;		/* saved group id */
+	u_int	 sc_pad;		/* padding, unused */
+	u_int	 sc_supp_groups_nb;	/* supplementary groups number */
+	gid_t	*sc_supp_groups;	/* supplementary groups */
+	struct mac *sc_label;		/* MAC label */
+};
+.Ed
+.Pp
+Its fields are:
+.Pp
+.Bl -tag -width "sc_supp_groups_nb   " -compact
+.It Fa sc_uid
+The ID to set the effective user to, if flag
+.Dv SETCREDF_UID
+is specified.
+.It Fa sc_ruid
+The ID to set the real user to, if flag
+.Dv SETCREDF_RUID
+is specified.
+.It Fa sc_svuid
+The ID to set the saved user to, if flag
+.Dv SETCREDF_SVUID
+is specified.
+.It Fa sc_gid
+The ID to set the effective group to, if flag
+.Dv SETCREDF_GID
+is specified.
+.It Fa sc_rgid
+The ID to set the real group to, if flag
+.Dv SETCREDF_RGID
+is specified.
+.It Fa sc_svgid
+The ID to set the saved group to, if flag
+.Dv SETCREDF_SVGID
+is specified.
+.It Fa sc_supp_groups_nb
+The size of array
+.Fa sc_supp_groups ,
+if flag
+.Dv SETCREDF_SUPP_GROUPS
+is specified.
+It must be less than or equal to
+.Dv {NGROUPS_MAX} .
+.It Fa sc_supp_groups
+An array of IDs to set the supplementary groups to, if flag
+.Dv SETCREDF_SUPP_GROUPS
+is specified.
+Note that all groups in this array will be set as supplementary groups only, in
+contrast to
+.Xr setgroups 2
+which treats the first element specially as the new effective group, not adding
+it to supplementary groups.
+.It Fa sc_label
+A pointer to a valid MAC label structure, e.g., built with the
+.Xr mac_from_text 3
+function, if flag
+.Dv SETCREDF_MAC_LABEL
+is specified.
+.El
+.Pp
+For forward compatibility and security reasons, it is recommended that users
+always initialize objects of type
+.Vt struct setcred
+with the provided initializer:
+.Dv SETCRED_INITIALIZER .
+.Pp
+The
+.Fa size
+argument must be the size of the passed
+.Fa wcred
+structure.
+.Sh RETURN VALUES
+.Rv -std
+.Sh ERRORS
+The
+.Fn setcred
+system call will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+Unrecognized flags were passed in
+.Fa flags ,
+or the
+.Fa size
+parameter does not match the size of
+.Vt struct setcred ,
+or the field
+.Fa sc_supp_group_nb
+has a value strictly greater than
+.Dv {NGROUPS_MAX}
+.Po if flag
+.Dv SETCREDF_SUPP_GROUPS
+was supplied
+.Pc ,
+or the MAC label pointed to by field
+.Fa sc_label
+is invalid
+.Po if flag
+.Dv SETCREDF_MAC_LABEL
+was supplied
+.Pc .
+.It Bq Er EFAULT
+The
+.Fa wcred
+pointer, or pointers in fields
+.Fa sc_supp_groups
+.Po if flag
+.Dv SETCREDF_SUPP_GROUPS
+was supplied
+.Pc
+or
+.Fa sc_label
+.Po if flag
+.Dv SETCREDF_MAC_LABEL
+was supplied
+.Pc
+point to invalid locations.
+.It Bq Er EPERM
+The user is not the super-user and/or the requested credentials transition is
+not allowed by the system or MAC modules.
+.It Bq Er EOPNOTSUPP
+Some of the requested credentials have a type that the system does not support.
+This currently can occur only if the kernel has been compiled without MAC and
+.Dv SETCREDF_MAC_LABEL
+has been passed.
+.El
+.Sh SEE ALSO
+.Xr issetugid 2 ,
+.Xr setregid 2 ,
+.Xr setreuid 2 ,
+.Xr setuid 2 ,
+.Xr mac_text 3 ,
+.Xr mac 4 ,
+.Xr mac_do 4 ,
+.Xr maclabel 7
+.Sh STANDARDS
+The
+.Fn setcred
+system call is specific to
+.Fx .
+.Pp
+A call to
+.Fn setcred
+usually changes process credentials that are listed by POSIX/SUS standards.
+The changed values then produce the effects with respect to the rest of the
+system that are described in these standards, as if these changes had resulted
+from calling standard or traditional credentials-setting functions.
+Currently, all flags but
+.Dv SETCREDF_MAC_LABEL
+lead to modifying standard credentials.
+.Pp
+The only differences in using
+.Fn setcred
+to change standard credentials instead of standard or traditional functions are:
+.Pp
+.Bl -bullet -compact
+.It
+All requested changes are performed atomically.
+.It
+Only the super-user or an unprivileged user authorized by some MAC module can
+successfully call
+.Fn setcred ,
+even if the standard system calls would have authorized any unprivileged user to
+effect the same changes.
+For example,
+.Fn seteuid
+allows any unprivileged user to change the effective user ID to either the real
+or saved ones, while
+.Fn setcred
+called with flag
+.Dv SETCREDF_UID
+does not.
+.El
+.Sh HISTORY
+The
+.Fn setcred
+system call appeared in
+.Fx 15.0 .
+.Pp
+Traditionally in UNIX, all credential changes beyond shuffles of effective, real
+and saved IDs have been done by setuid binaries that successively call multiple
+credentials-setting system calls and in a specific order.
+For example, to change all user IDs to that of some unprivileged user,
+.Fn setuid
+must be called last so that all other credentials-changing calls can be
+performed successfully beforehand, as they require super-user privileges.
+.Pp
+This piecewise approach causes such a process to transiently hold high privilege
+credentials that are neither the original nor necessarily the desired final
+ones.
+Besides opening a transition window where possible vulnerabilities could have
+catastrophic consequences, it makes it impossible for the kernel to enforce that
+only certain transitions of credentials are allowed.
+.Pp
+The necessity of an atomic, global approach to changing credentials clearly
+appeared while working on extending
+.Xr mac_do 4
+to allow rules to authorize only specific changes of primary or supplementary
+groups, which prompted the addition of
+.Fn setcred .
+.Sh AUTHORS
+The
+.Fn setcred
+system call and this manual page were written by
+.An Olivier Certner Aq Mt olce.freebsd@certner.fr .
+.Sh SECURITY CONSIDERATIONS
+The same considerations as those of standard or traditional credentials-setting
+system calls apply to
+.Fn setcred ,
+except for the lack of atomicity of successive such calls.
+.Pp
+In particular, please consult section
+.Sy SECURITY CONSIDERATIONS
+of the
+.Xr setuid 2
+manual page about the absence of effect of changing standard credentials on
+already open files.