diff options
Diffstat (limited to 'lib/libsys')
| -rw-r--r-- | lib/libsys/Symbol.map | 6 | ||||
| -rw-r--r-- | lib/libsys/getgroups.2 | 94 | ||||
| -rw-r--r-- | lib/libsys/jail.2 | 96 | ||||
| -rw-r--r-- | lib/libsys/kqueue.2 | 54 | ||||
| -rw-r--r-- | lib/libsys/setcred.2 | 7 | ||||
| -rw-r--r-- | lib/libsys/setgroups.2 | 99 |
6 files changed, 191 insertions, 165 deletions
diff --git a/lib/libsys/Symbol.map b/lib/libsys/Symbol.map index eb71c813ae86..ae12124ca210 100644 --- a/lib/libsys/Symbol.map +++ b/lib/libsys/Symbol.map @@ -4,10 +4,4 @@ FBSDprivate_1.0 { __getosreldate; __libsys_interposing_slot; _elf_aux_info; - freebsd11_fstat; - freebsd11_fstatat; - freebsd11_getfsstat; - freebsd11_lstat; - freebsd11_stat; - freebsd11_statfs; }; diff --git a/lib/libsys/getgroups.2 b/lib/libsys/getgroups.2 index 37c8fbad7215..4881a65d532e 100644 --- a/lib/libsys/getgroups.2 +++ b/lib/libsys/getgroups.2 @@ -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 +.\" <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 @@ -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 September 17, 2025 .Dt GETGROUPS 2 .Os .Sh NAME .Nm getgroups -.Nd get group access list +.Nd get the calling process' supplementary groups .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -40,36 +48,39 @@ .Sh DESCRIPTION The .Fn getgroups -system call -gets the current supplementary groups of the user process and stores it in the -array -.Fa gidset . -The +system call gets the calling process' supplementary groups and stores them in +the +.Fa gidset +array in strictly ascending order. +The value of .Fa gidsetlen -argument -indicates the number of entries that may be placed in +indicates the maximum number of entries that may be placed in .Fa gidset . -The -.Fn getgroups -system call -returns the actual number of groups returned in -.Fa gidset . -As many as {NGROUPS_MAX} values may be returned. +.Pp If .Fa gidsetlen is zero, .Fn getgroups -returns the number of supplementary group IDs associated with -the calling process without modifying the array pointed to by +returns the cardinal of the calling process' supplementary groups set and +ignores argument .Fa gidset . .Pp +No more than +.Dv {NGROUPS_MAX} +values may ever be returned. The value of .Dv {NGROUPS_MAX} should be obtained using .Xr sysconf 3 to avoid hard-coding it into the executable. .Sh RETURN VALUES -A successful call returns the number of groups in the group set. +On success, the +.Fn getgroups +system call returns the cardinal of the supplementary groups set. +It always succeeds if argument +.Fa gidsetlen +is zero. +.Pp A value of -1 indicates that an error occurred, and the error code is stored in the global variable .Va errno . @@ -81,12 +92,12 @@ are: .It Bq Er EINVAL The argument .Fa gidsetlen -is smaller than the number of groups in the group set. +is smaller than the number of supplementary groups +.Pq but not zero . .It Bq Er EFAULT -The argument +An invalid address was encountered while reading from the .Fa gidset -specifies -an invalid address. +array. .El .Sh SEE ALSO .Xr setgroups 2 , @@ -96,16 +107,51 @@ an invalid address. The .Fn getgroups system call conforms to -.St -p1003.1-2008 . +.St -p1003.1-2008 +with the additional properties that supplementary groups are reported in +strictly ascending order and the returned size coincides with the cardinal of +the set. .Sh HISTORY The .Fn getgroups system call appeared in .Bx 4.2 . .Pp +Since +.Fx 14.3 , +the +.Fn getgroups +system call has treated the supplementary groups as a set, reporting them in +strictly ascending order and returning the cardinal of the set. +.Pp Before .Fx 15.0 , the .Fn getgroups -system call always returned the effective group ID for the process as the first +system call would additionally return the effective group ID as the first element of the array, before the supplementary groups. +.Sh SECURITY CONSIDERATIONS +The +.Fn getgroups +system call gets the supplementary groups set in the +.Fa gidset +array. +In particular, as evoked in +.Sx HISTORY , +it does not anymore retrieve the effective GID in the first slot of +.Fa gidset . +Programs should not make any assumption about which group is placed in the first +slot of +.Fa gidset +other than it being the supplementary group with smallest GID. +.Pp +The effective GID is present in the supplementary groups set if and only if it +was explicitly set as a supplementary group. +The function +.Fn initgroups +enforces that, while the +.Fn setgroups +system call does not. +Please consult the +.Xr initgroups 3 +manual page for the rationale. diff --git a/lib/libsys/jail.2 b/lib/libsys/jail.2 index a0f47cc61cb3..ee4e5b03d38e 100644 --- a/lib/libsys/jail.2 +++ b/lib/libsys/jail.2 @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd September 4, 2025 +.Dd September 15, 2025 .Dt JAIL 2 .Os .Sh NAME @@ -340,31 +340,6 @@ work the same as and .Fn jail_remove , except that they operate on the jail referred to by the passed descriptor. -.Pp -Jail operations via descriptors can be done by processes that do not -normally have permission to see or affect the jail, -as long as they are allowed by the file permissions of the jail -descriptor itself. -These permissions can be changed by the descriptor owner via -.Xr fchmod 2 -and -.Xr fchown 2 . -.Fn jail_get -requires read permission, -.Fn jail_set -and -.Fn jail_remove -require write permission, -and -.Fn jail_attach -requires execute permission. -Also, use of a descriptor with the -.Dv JAIL_AT_DESC -flag requires execute permission. -An owning descriptor is identified by the -.Em sticky bit , -which may also be changed via -.Xr fchmod 2 . .Sh RETURN VALUES If successful, .Fn jail , @@ -402,31 +377,6 @@ The system call will fail if: .Bl -tag -width Er -.It Bq Er EBADF -The -.Va desc -parameter does not refer to a valid jail descriptor, -and either the -.Dv JAIL_USE_DESC -or -.Dv JAIL_AT_DESC -flag was set. -.It Bq Er EACCES -Write permission is denied on the jail descriptor in the -.Va desc -parameter, -and the -.Dv JAIL_USE_DESC -flag was set. -.It Bq Er EACCES -Execute permission is denied on the jail descriptor in the -.Va desc -parameter, -and either the -.Dv JAIL_AT_DESC -or -.Dv JAIL_ATTACH -flag was set. .It Bq Er EPERM This process is not allowed to create a jail, either because it is not the super-user, or because it would exceed the jail's @@ -514,33 +464,6 @@ The system call will fail if: .Bl -tag -width Er -.It Bq Er EBADF -The -.Va desc -parameter does not refer to a valid jail descriptor, -and either the -.Dv JAIL_USE_DESC -or -.Dv JAIL_AT_DESC -flag was set. -.It Bq Er EACCES -Read permission is denied on the jail descriptor in the -.Va desc -parameter, -and the -.Dv JAIL_USE_DESC -flag was set. -.It Bq Er EACCES -Execute permission is denied on the jail descriptor in the -.Va desc -parameter, -and the -.Dv JAIL_AT_DESC -flag was set. -.It Bq Er EFAULT -.Fa Iov , -or one of the addresses contained within it, -points to an address outside the allocated address space of the process. .It Bq Er ENOENT The jail referred to by a .Va jid @@ -564,6 +487,10 @@ parameter has been removed .It Bq Er EINVAL A supplied parameter is the wrong size. .It Bq Er EINVAL +A supplied parameter is out of range. +.It Bq Er EINVAL +A supplied string parameter is not null-terminated. +.It Bq Er EINVAL A supplied parameter name does not match any known parameters. .It Bq Er EMFILE A jail descriptor could not be created for the @@ -607,18 +534,10 @@ and system calls will fail if: .Bl -tag -width Er -.It Bq Er EBADF +.It Bq Er EINVAL The .Fa fd argument is not a valid jail descriptor. -.It Bq Er EACCES -Permission is denied on the jail descriptor -.Po -execute permission for -.Fn jail_attach_fd , -or write permission for -.Fn jail_remove_fd -.Pc . .It Bq Er EPERM The jail descriptor was created by a user other than the super-user. .It Bq Er EINVAL @@ -636,6 +555,9 @@ and call .Xr chroot 2 internally, so they can fail for all the same reasons. +In particular, they return the +.Bq Er EPERM +error when the process to join a jail has open directories. Please consult the .Xr chroot 2 manual page for details. diff --git a/lib/libsys/kqueue.2 b/lib/libsys/kqueue.2 index e413f7d4fbca..96c9b0222a37 100644 --- a/lib/libsys/kqueue.2 +++ b/lib/libsys/kqueue.2 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd September 4, 2025 +.Dd September 12, 2025 .Dt KQUEUE 2 .Os .Sh NAME @@ -614,41 +614,43 @@ The process ID will be stored in If more than one process has attached since the last call to .Fn kevent , .Va data -will contain the most recently attached process ID, -with -.Dv NOTE_JAIL_ATTACH_MULTI -set in -.Va fflags . +will be zero. .It Dv NOTE_JAIL_REMOVE The jail has been removed. .It Dv NOTE_JAIL_CHILD A child of the watched jail has been created. -.It Dv NOTE_TRACK -Follow child jails created under this jail. -Register a new kevent to monitor the child jail using the same -.Va fflags -as the original event. -The child jail will signal an event with -.Dv NOTE_CHILD -set in -.Va fflags -and the parent JID in +Its jail ID will be stored in .Va data . -.Pp -If registering a new kevent fails -.Pq usually due to resource limitations , -it will signal an event with -.Dv NOTE_TRACKERR -set in -.Va fflags , -and the child jail will not signal a -.Dv NOTE_CHILD -event. +If more than one jail has been created since the last call to +.Fn kevent , +.Va data +will be zero. .El .Pp On return, .Va fflags contains the events which triggered the filter. +It will also contain +.Dv NOTE_JAIL_MULTI +if more than one +.Dv NOTE_JAIL_ATTACH +or +.Dv NOTE_JAIL_CHILD +event has been received since the last call to +.Fn kevent . +.It Dv EVFILT_JAILDESC +Takes a jail descriptor returned by +.Xr jail_set 2 +or +.Xr jail_get 2 +as the identifier and the events to watch for in +.Va fflags , +and returns when the jail performs one or more of the requested events. +The events to monitor and the resulting +.Va fflags +are the same as those listed in +.Dv EVFILT_JAIL , +above. .It Dv EVFILT_TIMER Establishes an arbitrary timer identified by .Va ident . diff --git a/lib/libsys/setcred.2 b/lib/libsys/setcred.2 index 86f61ddfdb30..f5d1f15b631b 100644 --- a/lib/libsys/setcred.2 +++ b/lib/libsys/setcred.2 @@ -6,7 +6,7 @@ .\" This documentation was written by Olivier Certner <olce.freebsd@certner.fr> .\" at Kumacom SARL under sponsorship from the FreeBSD Foundation. .\" -.Dd December 19, 2024 +.Dd August 29, 2025 .Dt SETCRED 2 .Os .Sh NAME @@ -119,11 +119,6 @@ It must be less than or equal to 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 diff --git a/lib/libsys/setgroups.2 b/lib/libsys/setgroups.2 index 451f63ba1266..0ec99507cfb0 100644 --- 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.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 @@ -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 September 17, 2025 .Dt SETGROUPS 2 .Os .Sh NAME .Nm setgroups -.Nd set group access list +.Nd set the calling process' supplementary groups .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -41,21 +49,21 @@ .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 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 +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 0 to clear the supplementary group list. +argument may be set to zero to clear all supplementary groups, in which case +.Fa gidset +is ignored. .Pp -Only the super-user may set a new supplementary group list. +Only the super-user may install a new supplementary groups set. .Sh RETURN VALUES .Rv -std setgroups .Sh ERRORS @@ -69,16 +77,16 @@ The caller is not the super-user. 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 +Part of the groups array starting at .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,63 @@ the .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. +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 . |