mirror of
https://github.com/freebsd/freebsd-src.git
synced 2026-10-28 11:25:21 +01:00
Mark Johnston
dfc979fb8e
These routines let one compute the intersection of two sets of filecaps or capability rights, just as filecaps_merge() and cap_rights_merge() compute the union. This will be useful in an upcoming patch. filecaps_intersect() is complex due to the need to merge sets of ioctls. For now this is implemented with a dumb nested loop on the basis that ioctl lists are typically short enough that this is fine. It may be better to instead sort the two lists first and step through them together. No functional change intended. Approved by: so Security: FreeBSD-SA-26:66.jail Reviewed by: kib Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D59885
280 lines
6.8 KiB
Plaintext
280 lines
6.8 KiB
Plaintext
.\"
|
|
.\" Copyright (c) 2013 The FreeBSD Foundation
|
|
.\"
|
|
.\" This documentation was written by Pawel Jakub Dawidek 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 November 25, 2023
|
|
.Dt CAP_RIGHTS_INIT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cap_rights_init ,
|
|
.Nm cap_rights_set ,
|
|
.Nm cap_rights_clear ,
|
|
.Nm cap_rights_is_set ,
|
|
.Nm cap_rights_is_empty ,
|
|
.Nm cap_rights_is_valid ,
|
|
.Nm cap_rights_intersect ,
|
|
.Nm cap_rights_merge ,
|
|
.Nm cap_rights_remove ,
|
|
.Nm cap_rights_contains
|
|
.Nd manage cap_rights_t structure
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/capsicum.h
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_init "cap_rights_t *rights" "..."
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_set "cap_rights_t *rights" "..."
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_clear "cap_rights_t *rights" "..."
|
|
.Ft bool
|
|
.Fn cap_rights_is_set "const cap_rights_t *rights" "..."
|
|
.Ft bool
|
|
.Fn cap_rights_is_empty "const cap_rights_t *rights"
|
|
.Ft bool
|
|
.Fn cap_rights_is_valid "const cap_rights_t *rights"
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_intersect "cap_rights_t *dst" "const cap_rights_t *src"
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
|
|
.Ft cap_rights_t *
|
|
.Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
|
|
.Ft bool
|
|
.Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
|
|
.Sh DESCRIPTION
|
|
The functions documented here allow to manage the
|
|
.Vt cap_rights_t
|
|
structure.
|
|
.Pp
|
|
Capability rights should be separated with comma when passed to the
|
|
.Fn cap_rights_init ,
|
|
.Fn cap_rights_set ,
|
|
.Fn cap_rights_clear
|
|
and
|
|
.Fn cap_rights_is_set
|
|
functions.
|
|
For example:
|
|
.Bd -literal
|
|
cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
|
|
.Ed
|
|
.Pp
|
|
The complete list of the capability rights can be found in the
|
|
.Xr rights 4
|
|
manual page.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_init
|
|
function initialize provided
|
|
.Vt cap_rights_t
|
|
structure.
|
|
Only properly initialized structure can be passed to the remaining functions.
|
|
For convenience the structure can be filled with capability rights instead of
|
|
calling the
|
|
.Fn cap_rights_set
|
|
function later.
|
|
For even more convenience pointer to the given structure is returned, so it can
|
|
be directly passed to
|
|
.Xr cap_rights_limit 2 :
|
|
.Bd -literal
|
|
cap_rights_t rights;
|
|
|
|
if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
|
|
err(1, "Unable to limit capability rights");
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_set
|
|
function adds the given capability rights to the given
|
|
.Vt cap_rights_t
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_clear
|
|
function removes the given capability rights from the given
|
|
.Vt cap_rights_t
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_set
|
|
function checks if all the given capability rights are set for the given
|
|
.Vt cap_rights_t
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_empty
|
|
function checks if the
|
|
.Fa rights
|
|
structure is empty.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_valid
|
|
function verifies if the given
|
|
.Vt cap_rights_t
|
|
structure is valid.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_intersect
|
|
function clears all capability rights from the
|
|
.Fa dst
|
|
structure that are not present in the
|
|
.Fa src
|
|
structure, leaving only the rights common to both.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_merge
|
|
function merges all capability rights present in the
|
|
.Fa src
|
|
structure into the
|
|
.Fa dst
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_remove
|
|
function removes all capability rights present in the
|
|
.Fa src
|
|
structure from the
|
|
.Fa dst
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_contains
|
|
function checks if the
|
|
.Fa big
|
|
structure contains all capability rights present in the
|
|
.Fa little
|
|
structure.
|
|
.Sh RETURN VALUES
|
|
The functions never fail.
|
|
In case an invalid capability right or an invalid
|
|
.Vt cap_rights_t
|
|
structure is given as an argument, the program will be aborted.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_init ,
|
|
.Fn cap_rights_set
|
|
and
|
|
.Fn cap_rights_clear
|
|
functions return pointer to the
|
|
.Vt cap_rights_t
|
|
structure given in the
|
|
.Fa rights
|
|
argument.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_merge ,
|
|
.Fn cap_rights_remove
|
|
and
|
|
.Fn cap_rights_intersect
|
|
functions return pointer to the
|
|
.Vt cap_rights_t
|
|
structure given in the
|
|
.Fa dst
|
|
argument.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_set
|
|
returns
|
|
.Va true
|
|
if all the given capability rights are set in the
|
|
.Fa rights
|
|
argument.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_empty
|
|
function returns
|
|
.Va true
|
|
if none of the capability rights are set in the
|
|
.Fa rights
|
|
structure.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_is_valid
|
|
function performs various checks to see if the given
|
|
.Vt cap_rights_t
|
|
structure is valid and returns
|
|
.Va true
|
|
if it is.
|
|
.Pp
|
|
The
|
|
.Fn cap_rights_contains
|
|
function returns
|
|
.Va true
|
|
if all capability rights set in the
|
|
.Fa little
|
|
structure are also present in the
|
|
.Fa big
|
|
structure.
|
|
.Sh EXAMPLES
|
|
The following example demonstrates how to prepare a
|
|
.Vt cap_rights_t
|
|
structure to be passed to the
|
|
.Xr cap_rights_limit 2
|
|
system call.
|
|
.Bd -literal
|
|
cap_rights_t rights;
|
|
int fd;
|
|
|
|
fd = open("/tmp/foo", O_RDWR);
|
|
if (fd < 0)
|
|
err(1, "open() failed");
|
|
|
|
cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
|
|
|
|
if (allow_write_and_seek)
|
|
cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
|
|
|
|
if (dont_allow_seek)
|
|
cap_rights_clear(&rights, CAP_SEEK);
|
|
|
|
if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
|
|
err(1, "cap_rights_limit() failed");
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr cap_rights_limit 2 ,
|
|
.Xr open 2 ,
|
|
.Xr capsicum 4 ,
|
|
.Xr rights 4
|
|
.Sh HISTORY
|
|
The functions
|
|
.Fn cap_rights_init ,
|
|
.Fn cap_rights_set ,
|
|
.Fn cap_rights_clear ,
|
|
.Fn cap_rights_is_set ,
|
|
.Fn cap_rights_is_valid ,
|
|
.Fn cap_rights_merge ,
|
|
.Fn cap_rights_remove
|
|
and
|
|
.Fn cap_rights_contains
|
|
first appeared in
|
|
.Fx 8.3 .
|
|
Support for capabilities and capabilities mode was developed as part of the
|
|
.Tn TrustedBSD
|
|
Project.
|
|
.Sh AUTHORS
|
|
This family of functions was created by
|
|
.An Pawel Jakub Dawidek Aq Mt [email protected]
|
|
under sponsorship from the FreeBSD Foundation.
|