libc/capability/cap_rights_init.3

.\"
.\" 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.
.\"
.\" $FreeBSD$
.\"
.Dd May 5, 2020
.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_valid ,
.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_valid "const cap_rights_t *rights"
.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_valid
function verifies if the given
.Vt cap_rights_t
structure is valid.
.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
and
.Fn cap_rights_remove
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_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 pawel@dawidek.net
under sponsorship from the FreeBSD Foundation.