Page MenuHomeFreeBSD
Files F149325541

D52284.1789859491.diff
No OneTemporary
Actions

Size
3 KB
Referenced Files
None
Subscribers
None

D52284.1789859491.diff
View Options

diff --git a/lib/libsys/setgroups.2 b/lib/libsys/setgroups.2
--- a/lib/libsys/setgroups.2
+++ b/lib/libsys/setgroups.2
@@ -1,5 +1,13 @@
+.\"-
+.\" SPDX-License-Identifier: BSD-3-Clause
+.\"
.\" Copyright (c) 1983, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
+.\" Copyright (c) 2025 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Olivier Certner
+.\" <olce.freebsd@certner.fr> at Kumacom SARL under sponsorship from the FreeBSD
+.\" Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -25,12 +33,12 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 1, 2025
+.Dd August 29, 2025
.Dt SETGROUPS 2
.Os
.Sh NAME
.Nm setgroups
-.Nd set group access list
+.Nd set the current process' supplementary groups
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@@ -41,10 +49,10 @@
.Sh DESCRIPTION
The
.Fn setgroups
-system call
-sets the supplementary group list of the current user process
-according to the array
-.Fa gidset .
+system call sets the supplementary groups of the current process according to
+the
+.Fa gidset
+array.
The
.Fa ngroups
argument
@@ -53,9 +61,9 @@
.Dv {NGROUPS_MAX} .
The
.Fa ngroups
-argument may be set to 0 to clear the supplementary group list.
+argument may be set to 0 to clear all supplementary groups.
.Pp
-Only the super-user may set a new supplementary group list.
+Only the super-user may install a new supplementary group set.
.Sh RETURN VALUES
.Rv -std setgroups
.Sh ERRORS
@@ -69,16 +77,16 @@
The number specified in the
.Fa ngroups
argument is larger than the
-.Dv {NGROUPS_MAX}+1
+.Dv {NGROUPS_MAX}
limit.
.It Bq Er EFAULT
The address specified for
.Fa gidset
-is outside the process
-address space.
+is outside the process address space.
.El
.Sh SEE ALSO
.Xr getgroups 2 ,
+.Xr setcred 2 ,
.Xr initgroups 3
.Sh HISTORY
The
@@ -92,4 +100,38 @@
.Fn setgroups
system call would set the effective group ID for the process to the first
element of
-.Fa gidset .
+.Fa gidset ,
+and only the other elements as supplementary groups.
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn setgroups
+system call sets the process' supplementary groups to those contained in the
+.Fa gidset
+array.
+In particular, as evoked in
+.Sx HISTORY ,
+it does not anymore treat the first element of
+.Fa gidset
+separately, setting it as the effective GID while only the others were used as
+supplementary groups.
+.Pp
+Programs solely relying on
+.Fn setgroups
+to change the effective GID must be modified, e.g., to also call
+.Xr setegid 2
+or to instead use
+.Xr setcred 2 ,
+else they will unwillingly keep their effective GID.
+.Pp
+Programs using
+.Fn setgroups
+with the effective GID as the first element of
+.Fa gidset
+are now strictly speaking incorrect and should be modified.
+Not doing this modification may expose to unexpected behavior on subsequent
+process's effective GID's changes as these changes will not be able to entirely
+remove membership of the original effective GID since it will still be listed as
+a supplementary group.
+Programs that do not expect to change their effective GID themselves, nor spawn
+some setuid or setgid program to do that, are not affected but should preferably
+be modified defensively.

File Metadata

Mime Type
text/plain
Expires
Sat, Sep 19, 11:11 PM (5 h, 20 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29801679
Default Alt Text
D52284.1789859491.diff (3 KB)

Event Timeline