mirror of
https://github.com/opnsense/src.git
synced 2026-07-14 19:51:17 -04:00
7132fb5edb
Add a new SECURITY CONSIDERATIONS section describing in details what the new behavior is after commit9da2fe96ff("kern: fix setgroups(2) and getgroups(2) to match other platforms"), what setgroups(2) does not do anymore, and how programs using it are affected. Fix the groups limit after commit9da2fe96ff("kern: fix setgroups(2) and getgroups(2) to match other platforms"). Prefer a terminology referring to POSIX terms, i.e., use "effective group list" instead of "group access list". While here, fix some style. Note for MFC to stable/14: The content will have to be revised as the new behavior is not in place. The latter should still be mentioned as upcoming in 15. Fixes:9da2fe96ff("kern: fix setgroups(2) and getgroups(2) to match other platforms") MFC after: 5 days Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D52284 (cherry picked from commit 6d22cd6b5f8b5604f1fe9e70930b1506f990e31e)
162 lines
4.8 KiB
Groff
162 lines
4.8 KiB
Groff
.\"-
|
|
.\" 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.org> 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
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd September 17, 2025
|
|
.Dt SETGROUPS 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm setgroups
|
|
.Nd set the calling process' supplementary groups
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In unistd.h
|
|
.Ft int
|
|
.Fn setgroups "int ngroups" "const gid_t *gidset"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn setgroups
|
|
system call sets the calling process' supplementary groups according to the
|
|
.Fa gidset
|
|
array.
|
|
The
|
|
.Fa ngroups
|
|
argument indicates the number of entries in the array and must be no more than
|
|
.Dv {NGROUPS_MAX} .
|
|
.Pp
|
|
The
|
|
.Fa ngroups
|
|
argument may be set to zero to clear all supplementary groups, in which case
|
|
.Fa gidset
|
|
is ignored.
|
|
.Pp
|
|
Only the super-user may install a new supplementary groups set.
|
|
.Sh RETURN VALUES
|
|
.Rv -std setgroups
|
|
.Sh ERRORS
|
|
The
|
|
.Fn setgroups
|
|
system call will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EPERM
|
|
The caller is not the super-user.
|
|
.It Bq Er EINVAL
|
|
The number specified in the
|
|
.Fa ngroups
|
|
argument is larger than the
|
|
.Dv {NGROUPS_MAX}
|
|
limit.
|
|
.It Bq Er EFAULT
|
|
Part of the groups array starting at
|
|
.Fa gidset
|
|
is outside the process address space.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr getgroups 2 ,
|
|
.Xr setcred 2 ,
|
|
.Xr initgroups 3
|
|
.Sh HISTORY
|
|
The
|
|
.Fn setgroups
|
|
system call appeared in
|
|
.Bx 4.2 .
|
|
.Pp
|
|
Before
|
|
.Fx 15.0 ,
|
|
the
|
|
.Fn setgroups
|
|
system call would set the effective group ID for the process to the first
|
|
element of
|
|
.Fa gidset ,
|
|
and only the other elements as supplementary groups.
|
|
Despite treating the first element as the effective group ID to set, it accepted
|
|
an empty
|
|
.Fa gidset
|
|
.Po
|
|
.Fa ngroups
|
|
being zero
|
|
.Pc
|
|
as a stance requiring to drop all supplementary groups, leaving the effective
|
|
group ID unchanged.
|
|
.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.
|
|
Formerly, it would set it as the effective group ID while only the others were
|
|
used as supplementary groups.
|
|
.Pp
|
|
Programs solely relying on
|
|
.Fn setgroups
|
|
to change the effective group ID 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 group ID.
|
|
.Pp
|
|
Programs using
|
|
.Fn setgroups
|
|
with the effective group ID as the first element of array
|
|
.Fa gidset
|
|
and not duplicating it in the rest of the array, which includes those using
|
|
.Fn initgroups ,
|
|
now insert this group ID in the supplementary groups set.
|
|
This is in general desirable, as explained in the
|
|
.Xr initgroups 3
|
|
manual page, and has the consequence that subsequent process' effective group
|
|
ID's changes do not remove membership of the original effective group ID, since
|
|
these changes do not affect the supplementary groups.
|
|
Applications that expressly do not want that must be modified to stop passing
|
|
the effective group ID as the first element to
|
|
.Fn setgroups .
|
|
.Pp
|
|
To clear all the calling process' supplementary groups, always use the statement
|
|
.Bd -literal -offset indent
|
|
setgroups(0, NULL);
|
|
.Ed
|
|
.Pp
|
|
which works also on older FreeBSD version
|
|
.Po
|
|
see the
|
|
.Sx HISTORY
|
|
section
|
|
.Pc .
|