From nobody Wed Sep 17 12:19:16 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4cRd9c5BjBz67Hsh; Wed, 17 Sep 2025 12:19:16 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4cRd9c2TFqz3Vyr; Wed, 17 Sep 2025 12:19:16 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1758111556; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=qcBbuHgzZRET/YtftAoERB2dRdsOlhdN6okMRzBSAsE=; b=QrYizEhm4uhWL2YO3zevNAhoV3xS2fO3xJft0V+m959Lm0+TyWSq49plmjf16f6eGJgAro J1nGrrT9XUi9/zCmxHLaRKWbRFrAfiuaVquT/vLniQILLh7ya1XVgF4R7fTvey4EcuvUSh +lwT0laCsmFXSFDRK9vz7Ar6MPsRyQ+/+1TcdQHgAOitsTF4+eaS1EGJsWfXuHFGiuQdWL 4fLoD5l0l8R80ECaClkwSpZplpeyff5fmd16q/daLnUr3IogcIuAP48EUmBWSKV13CYpZ5 81+FHkMfEMs1GJ4LpyEcagp4trkT2KQALcTITYdD3bRzPy4jZmhS5f9QBOBl3A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1758111556; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=qcBbuHgzZRET/YtftAoERB2dRdsOlhdN6okMRzBSAsE=; b=WTEI0mL9X0p2Rly5S+t66xpN8DLKeWUOeFjPcTgQeDBkgKFKpp2Mkcx8Ddraaeknzbgf/u vlRfYanjWc5F4tHeXwp8TEt67iierS7+XQoBPMrhsryCdsd5RhGuh4trrefhxGZfsJNv6l 7xlfKdeS+1Kuk8I3lMDsI+B4itzSSbRXi7BdqffdTKyYvhY8FaWdUVRD4QNSWA8UnnJgJW 97ufv6wOcIRFZCXXljkjajkoliNeDh23NVpJ3mENy/ImvOhb/BjIXEB3JHnf9n2WeeQNQm sG2SUmk3VTZGRuWtJdjQ1ASAfzbcvt7Q489pvN5uJ0F+ez6qAMb5lTrAUXkhMw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1758111556; a=rsa-sha256; cv=none; b=E+IGoiAgIvViy27XSUkFPIbSh1mCMjDZBPeVsdGS6GxjhKlY49afYswwQl9pbtGDg7xMHz IUiW8+YB763Ct9C0xWcPyTZVEI9YMq5c2D70B39h0Gf7wQ0C8LdtJR8oYWKYtisvM70ut6 blI52I7xmOWdOsFBnW+JVXdzqPcyAmQHC1SCgeQktxd8D/lVVI0Rm7bzVqKFNH1eLNqAmg V57d/+LoG13YfXjj8a3Y2TdwTmhgrp+tPT7ZovDIqSMITsbB50vmdhmwcCpibEh4gzSYqx pfVTWSRExFoVohhC5aVpHtLjBEqfsEtPyOC50rTNtr+FjhJnSl7FbTn7MxJncA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4cRd9c236Mz9Ls; Wed, 17 Sep 2025 12:19:16 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 58HCJGB3086092; Wed, 17 Sep 2025 12:19:16 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 58HCJGuA086088; Wed, 17 Sep 2025 12:19:16 GMT (envelope-from git) Date: Wed, 17 Sep 2025 12:19:16 GMT Message-Id: <202509171219.58HCJGuA086088@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Olivier Certner Subject: git: 9dc1ac869196 - main - initgroups(3): Add a pre-FreeBSD-15-compatible version List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: olce X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 9dc1ac8691966480ff8bd9c37dd405b981b41dd5 Auto-Submitted: auto-generated The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/src/commit/?id=9dc1ac8691966480ff8bd9c37dd405b981b41dd5 commit 9dc1ac8691966480ff8bd9c37dd405b981b41dd5 Author: Olivier Certner AuthorDate: 2025-08-29 14:19:33 +0000 Commit: Olivier Certner CommitDate: 2025-09-17 12:16:06 +0000 initgroups(3): Add a pre-FreeBSD-15-compatible version After commit 9da2fe96ff2e ("kern: fix setgroups(2) and getgroups(2) to match other platforms"), initgroups() does not set the effective GID anymore and uses all passed groups as the supplementary group list. This effectively breaks backwards compatibility with programs/libraries compiled on a FreeBSD 14 or earlier system. Restore compatibility by creating a new version of the 'initgroups' symbol that designates the current implementation and providing a pre-FreeBSD-15-compatible version under the symbol's previously exported version. The new version calls the new setgroups(2) system call, while the compatible one calls the original one (called freebsd14_setgroups()). Update the manual page with some history and comparison with other current open-source systems. Add a "SECURITY CONSIDERATIONS" section highlighting some security properties of this approach and the reasons we adopt it. While here, revamp the manual page, in particular to use the exact POSIX terminology where possible. Note for MFC to stable/14: Only the manual page update is to be MFCed, and the text changed to reflect the old behavior and inform readers of the new upcoming behavior in 15. Reviewed by: kib Fixes: 9da2fe96ff2e ("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/D52282 --- lib/libc/gen/Symbol.map | 2 +- lib/libc/gen/gen-compat.h | 2 + lib/libc/gen/initgroups.3 | 101 +++++++++++++++++++++++++++++++++++++++------- lib/libc/gen/initgroups.c | 44 +++++++++++++++----- 4 files changed, 124 insertions(+), 25 deletions(-) diff --git a/lib/libc/gen/Symbol.map b/lib/libc/gen/Symbol.map index 26f638568efc..494b65bc5cc1 100644 --- a/lib/libc/gen/Symbol.map +++ b/lib/libc/gen/Symbol.map @@ -193,7 +193,6 @@ FBSD_1.0 { __isinff; __isinfl; isatty; - initgroups; jrand48; lcong48; ldexp; @@ -462,6 +461,7 @@ FBSD_1.8 { fdscandir_b; fts_open_b; glob_b; + initgroups; inotify_add_watch; inotify_init; inotify_init1; diff --git a/lib/libc/gen/gen-compat.h b/lib/libc/gen/gen-compat.h index 08e80ede6b6e..dac8f54b45a2 100644 --- a/lib/libc/gen/gen-compat.h +++ b/lib/libc/gen/gen-compat.h @@ -52,4 +52,6 @@ int freebsd11_getmntinfo(struct freebsd11_statfs **, int); char *freebsd11_devname(__uint32_t dev, __mode_t type); char *freebsd11_devname_r(__uint32_t dev, __mode_t type, char *buf, int len); +int freebsd14_setgroups(int gidsize, const __gid_t *gidset); + #endif /* _GEN_COMPAT_H_ */ diff --git a/lib/libc/gen/initgroups.3 b/lib/libc/gen/initgroups.3 index 03bd07494fc9..4f538fb180ec 100644 --- a/lib/libc/gen/initgroups.3 +++ b/lib/libc/gen/initgroups.3 @@ -1,5 +1,13 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" .\" Copyright (c) 1983, 1991, 1993 .\" 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 +.\" 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 October 26, 2014 +.Dd September 17, 2025 .Dt INITGROUPS 3 .Os .Sh NAME .Nm initgroups -.Nd initialize group access list +.Nd initialize supplementary groups as per the group database .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -40,19 +48,18 @@ .Sh DESCRIPTION The .Fn initgroups -function -uses the -.Xr getgrouplist 3 -function to calculate the group access list for the user -specified in +function initializes the current process' supplementary groups as prescribed by +its arguments and the system's group database. +.Pp +It first uses the +.Fn getgrouplist +function to compute a list of groups containing the passed +.Fa basegid , +which typically is the user's initial numerical group ID from the password +database, and the supplementary groups in the group database for the user named .Fa name . -This group list is then setup for the current process using -.Xr setgroups 2 . -The -.Fa basegid -is automatically included in the groups list. -Typically this value is given as -the group number from the password file. +It then installs this list as the current process' supplementary groups using +.Fn setgroups . .Sh RETURN VALUES .Rv -std initgroups .Sh ERRORS @@ -60,7 +67,7 @@ The .Fn initgroups function may fail and set .Va errno -for any of the errors specified for the library function +to any of the errors specified for the library function .Xr setgroups 2 . It may also return: .Bl -tag -width Er @@ -77,3 +84,67 @@ The .Fn initgroups function appeared in .Bx 4.2 . +.Pp +The +.Fn initgroups +function changed semantics in +.Fx 15 , +following that of +.Xr setgroups 2 +in the same release. +Before that, it would also set the effective group ID to +.Fa basegid , +and would not include the latter in the supplementary groups except before +.Fx 8 . +Its current behavior in these respects is known to be compatible with that of +the following systems up to the specified versions that are current at time of +this writing: +.Bl -dash -width "-" -compact +.It +Linux (up to 6.6) with the GNU libc (up to 2.42) +.It +.Nx 1.1 and greater (up to 10) +.It +.Ox (up to 7.7) +.It +Systems based on illumos (up to August 2025 sources) +.El +.Sh SECURITY CONSIDERATIONS +As +.Fa basegid +is typically the user's initial numerical group ID, to which the current +process' effective group ID is generally initialized, processes using functions +to change their effective group ID +.Pq via Xr setgid 2 or similar +or that are spawned from executables with the set-group-ID mode bit set will not +be able to relinquish the access rights deriving from being a member of +.Fa basegid , +as these functions do not change the supplementary groups. +.Pp +This behavior is generally desirable in order to paper over the difference of +treatment between the effective group and supplementary ones in this situation, +as they are all in the end indiscriminately used in traditional UNIX +discretionary access checks. +It blends well with the practice of allocating each user its own private group, +as processes launched from a set-group-ID executable keep the same user and +consistently stay also in the same user's group. +Finally, it was also chosen for compatibility with other systems +.Po +see the +.Sx HISTORY +section +.Pc . +.Pp +This convention of including +.Fa basegid +in the supplementary groups is however only enforced by the +.Fn initgroups +function, and not by the +.Xr setgroups 2 +system call, so applications expressly wanting to include in the supplementary +groups only those specified by the group database can themselves call +.Fn getgrouplist +and then +.Fn setgroups +on the result with the first element skipped +.Pq see Xr getgrouplist 3 . diff --git a/lib/libc/gen/initgroups.c b/lib/libc/gen/initgroups.c index 55f17a94fa8e..a1a7d92250e2 100644 --- a/lib/libc/gen/initgroups.c +++ b/lib/libc/gen/initgroups.c @@ -3,6 +3,11 @@ * * Copyright (c) 1983, 1993 * The Regents of the University of California. All rights reserved. + * Copyright (c) 2025 The FreeBSD Foundation + * + * Portions of this software were developed by Olivier Certner + * 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 @@ -29,22 +34,28 @@ * SUCH DAMAGE. */ -#include +/* For __sym_compat(). */ +#include #include #include #include -int -initgroups(const char *uname, gid_t agroup) +/* For freebsd14_setgroups(). */ +#include "gen-compat.h" + +static int +initgroups_impl(const char *uname, gid_t agroup, + int (*setgroups)(int, const gid_t *)) { - int ngroups, ret; - long ngroups_max; gid_t *groups; + long ngroups_max; + int ngroups, ret; /* - * Provide space for one group more than possible to allow - * setgroups to fail and set errno. + * Provide space for one group more than possible to allow setgroups() + * to fail and set 'errno' in case we get back more than {NGROUPS_MAX} + + * 1 groups. */ ngroups_max = sysconf(_SC_NGROUPS_MAX) + 2; groups = malloc(sizeof(*groups) * ngroups_max); @@ -52,8 +63,23 @@ initgroups(const char *uname, gid_t agroup) return (-1); /* malloc() set 'errno'. */ ngroups = (int)ngroups_max; - getgrouplist(uname, agroup, groups, &ngroups); - ret = setgroups(ngroups, groups); + (void)getgrouplist(uname, agroup, groups, &ngroups); + ret = (*setgroups)(ngroups, groups); + free(groups); return (ret); /* setgroups() set 'errno'. */ } + +int +initgroups(const char *uname, gid_t agroup) +{ + return (initgroups_impl(uname, agroup, setgroups)); +} + +int +freebsd14_initgroups(const char *uname, gid_t agroup) +{ + return (initgroups_impl(uname, agroup, freebsd14_setgroups)); +} + +__sym_compat(initgroups, freebsd14_initgroups, FBSD_1.0);