From nobody Sun Oct 19 17:35:39 2025 X-Original-To: dev-commits-doc-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 4cqQgv2BJ6z6DVNG for ; Sun, 19 Oct 2025 17:35:39 +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 4cqQgv1CFFz3rXC; Sun, 19 Oct 2025 17:35:39 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760895339; 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=n7Jr5SkSXx8M/i/54p13hGdQECVoHoGTd5zyV0BeXvA=; b=SznCD+/D5HJ0+bQx1bIB/VCFDxO6Qpx09hrOGpm5k/kBoVmFl/fVWJ9/v/PTntt5djyoPt G1HRFCgwiNPTXpK7w2KkAg/4xeIwcFWycOMqy5d1CQPb2R7q+lGDsh7IeEmR8mSIWLu0sF Phfb3y1+vOj25N9791qBfwWo6gVsljbSMlFRGWAFInyuyn/L2SwJSlqMU4UpwjYZxWZ+Vy WH+0JSJIupoMeF/mOUOzmFSZCvUZIKURERay1DaaLJwtgIrz5CbjAytbIsi1k4gU9ryK4V hgmRsAinMM24exyh9oSmn++Napiw+mg/Ylts89fJFMcRj6ath24T3dcZ5iOsdw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1760895339; 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=n7Jr5SkSXx8M/i/54p13hGdQECVoHoGTd5zyV0BeXvA=; b=NFuurItAnbkNo+usU6uoZwl54slIdi8+WnlCCOmuzDDpdOp03v+0frBq752sVi/RT3DyoC US0WyplqkJNrja46etVsUG8mlsyFZo7fUadCh1071rBgK4REpCzZJzQG9xT0NkxNCyn8wH T4CFNpkKv/nZKAP9ubFWXGijA0O3zRYKoy2QXSjjQgJEufg+JeGaihimSsSTbplTrZUQbe umjL2tBuXx0uP2/si/Bo+/Jx3TFF51alfsOb0q09BojydF13h/gbs9l0HaYXE/4+XN/2Bj MaByRSAsVhc7my0FlTPfvFKgAcX+/0ODs4io6NCmpqeWxjAGDzS0R1yZIrtfRg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1760895339; a=rsa-sha256; cv=none; b=KOIeIDZnmg9qAv9hBvEyhgUFhwYcIASL+xpKuqVmzUu8RIEVrVMSYK8o6ItvDNbxJoRbtg +K9yLMCEdTssRm3QL5bcBKALpaHAuucBPrlJ8GXSSK7YBm+zbLBTXrgLGq7VfBbp/FvzhP xIxFtdLqKGSflLE7C5bILehN2cs0SuAnKBDvNyzCSOdqKxLQr0QbscZvQWyiuydGSzUN11 PMpkhn2VltrkmPJ38YkoGJ7Bn6N4UKB7xG6xDlxQSNjwXZKEdw/Brb1ei3AqbW85pM5u1A 6T3GCNsSQJATuzgoXQwQDk43z8NLuC3L8rHgTh6Ng6U6uRrOfISiQEx8J1xYtQ== 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 4cqQgv0dNrzdSN; Sun, 19 Oct 2025 17:35:39 +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 59JHZdaF077547; Sun, 19 Oct 2025 17:35:39 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 59JHZdFm077544; Sun, 19 Oct 2025 17:35:39 GMT (envelope-from git) Date: Sun, 19 Oct 2025 17:35:39 GMT Message-Id: <202510191735.59JHZdFm077544@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Olivier Certner Subject: git: 500bae4fb8 - main - Status/2025Q3/group-changes.adoc: Add report List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-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: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 500bae4fb849c8da92002500644203d99b7f0209 Auto-Submitted: auto-generated The branch main has been updated by olce: URL: https://cgit.FreeBSD.org/doc/commit/?id=500bae4fb849c8da92002500644203d99b7f0209 commit 500bae4fb849c8da92002500644203d99b7f0209 Author: Olivier Certner AuthorDate: 2025-10-19 17:33:56 +0000 Commit: Olivier Certner CommitDate: 2025-10-19 17:35:25 +0000 Status/2025Q3/group-changes.adoc: Add report This is a report concerning credentials' group-related changes and in particular the project of improving the behavior of setgroups(2)/getgroups(2) and initgroups(3) to avoid security pitfalls and be compatible with most other open-source systems. It follows the similarly named report for T2 2025, which is linked from this new one. Sponsored by: The FreeBSD Foundation --- .../report-2025-07-2025-09/group-changes.adoc | 44 ++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/website/content/en/status/report-2025-07-2025-09/group-changes.adoc b/website/content/en/status/report-2025-07-2025-09/group-changes.adoc new file mode 100644 index 0000000000..2eba794c5e --- /dev/null +++ b/website/content/en/status/report-2025-07-2025-09/group-changes.adoc @@ -0,0 +1,44 @@ +=== Process Credentials' Groups-Related Changes in FreeBSD 15 + +Links: + +link:https://www.freebsd.org/status/report-2025-04-2025-06/#_ucred_group_changes_in_freebsd_15_0[T2 2025 Status Report] URL: https://www.freebsd.org/status/report-2025-04-2025-06/#_ucred_group_changes_in_freebsd_15_0 + +link:https://cgit.freebsd.org/src/commit/?id=9dc1ac869196[initgroups(3): Backwards-compatible implementation and manual page update ] URL: https://cgit.freebsd.org/src/commit/?id=9dc1ac869196 + +link:https://cgit.freebsd.org/src/commit/?id=4be38acc826f[Main commit changing getgroups(2)'s manual page] URL: https://cgit.freebsd.org/src/commit/?id=4be38acc826f + +link:https://cgit.freebsd.org/src/commit/?id=6d22cd6b5f8b[Main commit changing setgroups(2)'s manual page] URL: https://cgit.freebsd.org/src/commit/?id=6d22cd6b5f8b + +Contact: Olivier Certner + +Contact: Kyle Evans + +Starting with FreeBSD 15: + +. [[setgroups_getgroups]]The behavior of the man:setgroups[2] and man:getgroups[2] system calls function has slightly changed. ++ +Out of caution, even if almost all existing applications will continue to work undisturbed, we advise auditing those that you are maintaining or using as explained below. +. [[initgroups]]How processes' group membership is derived from the password and group databases on login has slightly changed: The login user's initial numerical group ID from the password database is now automatically added to the supplementary groups set, even if that user is not explicitly listed as a member of the corresponding group in the group database. +. [[kernel]]The kernel stores the effective group ID in a new specific field of `struct ucred` (`cr_gid`) instead of in the same array as supplementary groups (`cr_ngroups[]`). + +The man:setgroups[2] and man:getgroups[2] system calls will operate only on the calling process' supplementary groups, not featuring the effective group ID as the first element of their array argument. +The man:initgroups[3] function's implementation is unchanged and still relies on man:setgroups[2], with the consequence that it **does not** set the process' effective group ID **anymore**, instead including its `basegid` argument in the supplementary groups set. + +One of the reasons for these changes is to have FreeBSD behave exactly like GNU/Linux systems, NetBSD, OpenBSD and illumos-based operating systems. +Consequently, almost all portable applications should already be compliant with FreeBSD's new behavior and will continue to work correctly or even get fixed in the process (see the previous status report linked above for an example with OpenSSH). +However, porters, system administrators and users are advised to audit their applications that are using man:setgroups[2], man:getgroups[2] and man:initgroups[3], watching out for the following points: + +* Applications should already be using man:setgid[2] or man:setegid[2] in addition to man:setgroups[2] or man:initgroups[3] to set the effective group ID. ++ +If this is not the case, these calls must be added, as otherwise affected applications will stop setting the effective group ID starting from FreeBSD 15. +* Applications using man:getgroups[2] should not be treating the first element of the returned array specially, but as any other supplementary group. ++ +If nonetheless they do, they have to be modified to obtain the effective group ID via man:getegid[2] instead and to treat all groups returned by man:getgroups[2] as supplementary groups only. + +Manual pages of all changed functions have been modified in `stable/14` and `stable/15` to describe and contrast the old and new behaviors, and have grown new `SECURITY CONSIDERATIONS` sections stating the reasons for the changes and the points to watch out for. + +Backwards-compatible implementations of changed functions are provided so that applications compiled on FreeBSD 14 or earlier continue to see the old behaviors and work as before. +They are available if and only if the kernel was compiled with `COMPAT_FREEBSD14`, which is the case of the default `GENERIC` kernel. + +We have normally fixed all unwanted impacts of storing the effective group ID separately from the supplementary groups in the kernel, such as: + +* Some security policies or access checks would either ignore the effective group ID or the first supplementary group (with lowest numerical ID), affecting process visibility restrictions based on group IDs, the "can debug" and "can export KTLS keys" checks, the man:mac_do[4] and man:mac_bsdextended[4] security policies, and access crontrol to some hardware facilities (tracing: man:hwt[4]; performance monitoring: man:hwpmc[4]) and to NFS-served shares. +* Reporting of process' credentials would omit the effective group ID, affecting all variants of `procstat -s` (on live processes, core files, or system core dump), man:ddb[4]. + +Sponsor: The FreeBSD Foundation