diff options
Diffstat (limited to 'static/freebsd/man3/cap_fileargs.3')
| -rw-r--r-- | static/freebsd/man3/cap_fileargs.3 | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/static/freebsd/man3/cap_fileargs.3 b/static/freebsd/man3/cap_fileargs.3 new file mode 100644 index 00000000..6a69fe7e --- /dev/null +++ b/static/freebsd/man3/cap_fileargs.3 @@ -0,0 +1,300 @@ +.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org> +.\" All rights reserved. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 August 8, 2025 +.Dt CAP_FILEARGS 3 +.Os +.Sh NAME +.Nm cap_fileargs , +.Nm fileargs_cinit , +.Nm fileargs_cinitnv , +.Nm fileargs_init , +.Nm fileargs_initnv , +.Nm fileargs_free , +.Nm fileargs_lstat , +.Nm fileargs_open , +.Nm fileargs_fopen +.Nd "library for handling files in capability mode" +.Sh SYNOPSIS +.Lb libcap_fileargs +.In sys/nv.h +.In libcasper.h +.In casper/cap_fileargs.h +.Ft "fileargs_t *" +.Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations" +.Ft "fileargs_t *" +.Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations" +.Ft "fileargs_t *" +.Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits" +.Ft "fileargs_t *" +.Fn fileargs_initnv "nvlist_t *limits" +.Ft "void" +.Fn fileargs_free "fileargs_t *fa" +.Ft "int" +.Fn fileargs_lstat "fileargs_t *fa" "const char *path" "struct stat *sb" +.Ft "int" +.Fn fileargs_open "fileargs_t *fa" "const char *name" +.Ft "FILE *" +.Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode" +.Ft "char *" +.Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path" +.Sh DESCRIPTION +The +.Nm +library is used to simplify Capsicumizing tools that are using file system. +The idea behind the library is that we pass the remaining arguments from +.Fa argv +(with count specified by +.Fa argc ) +which contains the list of files that should be opened by the program. +The library creates a service that will serve those files. +.Pp +The function +.Fn fileargs_init +creates a service to the +.Nm system.fileargs . +The +.Fa argv +contains a list of files that should be opened. +The argument can be set to +.Dv NULL +to create no service and prohibit all files from being opened. +The +.Fa argc +argument contains the number of files passed to the program. +The +.Fa flags +argument specifies whether files can be opened for execution, for reading, +and/or for writing. +The +.Fa mode +argument specifies the permissions to use when creating new files if the +.Dv O_CREAT +flag is set. +For more information about the +.Fa flags +and +.Fa mode +arguments, see +.Xr open 2 . +The +.Fa rightsp +argument specifies the capability rights that will be applied to restrict +access to the files. +For more information about capability rights, see +.Xr cap_rights_init 3 . +The +.Fa operations +argument specifies which operations are permitted when using +.Nm system.fileargs . +The following flags can be combined to form the +.Fa operations +value: +.Bl -ohang -offset indent +.It FA_OPEN +Allow +.Fn fileargs_open +and +.Fn fileargs_fopen . +.It FA_LSTAT +Allow +.Fn fileargs_lstat . +.It FA_REALPATH +Allow +.Fn fileargs_realpath . +.El +.Pp +The function +.Fn fileargs_cinit +behaves identically to +.Fn fileargs_init , +but requires an existing Casper connection to be passed as an argument. +.Pp +The functions +.Fn fileargs_initnv +and +.Fn fileargs_cinitnv +are equivalent to +.Fn fileargs_init +and +.Fn fileargs_cinit +respectively, but take their arguments in the form of an +.Xr nvlist 9 +structure. +See the +.Sx LIMITS +section for details on the expected argument types and values. +.Pp +The +.Fn fileargs_free +function closes the connection to the +.Nm system.fileargs +service and frees all associated data structures. +The function safely handles +.Dv NULL +arguments. +.Pp +The function +.Fn fileargs_lstat +provides the same functionality as +.Xr lstat 2 . +.Pp +The functions +.Fn fileargs_open +and +.Fn fileargs_fopen +behave identically to +.Xr open 2 +and +.Xr fopen 3 +respectively, but retrieve their arguments from the +.Va fileargs_t +structure. +.Pp +The function +.Fn fileargs_realpath +provides the same functionality as the standard C library function +.Xr realpath 3 , +resolving all symbolic links and references in a pathname. +.Pp +The following functions are reentrant but require synchronization for +thread safety: +.Fn fileargs_open , +.Fn fileargs_lstat , +.Fn fileargs_realpath , +.Fn fileargs_cinitnv , +.Fn fileargs_initnv , +and +.Fn fileargs_fopen . +Multiple threads can call these functions safely only if they use different +.Vt cap_channel_t +arguments or proper synchronization mechanisms. +.Sh LIMITS +This section describes the required and optional arguments that must be +passed to +.Fa system.fileargs +via the +.Fn fileargs_initnv +and +.Fn fileargs_cinitnv +functions using an +.Xr nvlist 9 +structure. +.Pp +The following arguments are required: +.Bl -ohang -offset indent +.It flags Pq Dv NV_TYPE_NUMBER +Specifies access permissions for opened files. +.It mode Pq Dv NV_TYPE_NUMBER +Required when the +.Dv O_CREATE +flag is set in +.Va flags . +Specifies the permissions to use when creating new files. +.It operations Pq Dv NV_TYPE_NUMBER +Specifies which operations are allowed for +.Fa system.fileargs . +See the description of the +.Va operations +argument in +.Fn fileargs_init +for possible values. +.El +.Pp +The following arguments are optional in the +.Xr nvlist 9 +structure: +.Bl -ohang -offset indent +.It cap_rights Pq Dv NV_TYPE_BINARY +The +.Va cap_rights +argument specifies the capability rights that will be applied to restrict +access to opened files. +.It filenames Pq Dv NV_TYPE_NULL +Multiple +.Dv NV_TYPE_NULL +elements can be provided, where each element's name represents a file +path that is allowed to be opened. +.El +.Sh EXAMPLES +.Bd -literal +int ch, fd, i; +cap_rights_t rights; +fileargs_t *fa; + +while ((ch = getopt(argc, argv, "h")) != -1) { + switch (ch) { + case 'h': + default: + usage(); + } +} + +argc -= optind; +argv += optind; + +/* Create capability to the system.fileargs service. */ +fa = fileargs_init(argc, argv, O_RDONLY, 0, + cap_rights_init(&rights, CAP_READ), FA_OPEN); +if (fa == NULL) + err(1, "unable to open system.fileargs service"); + +/* Enter capability mode sandbox. */ +if (cap_enter() < 0 && errno != ENOSYS) + err(1, "unable to enter capability mode"); + +/* Open files. */ +for (i = 0; i < argc; i++) { + fd = fileargs_open(fa, argv[i]); + if (fd < 0) + err(1, "unable to open file %s", argv[i]); + printf("File %s opened in capability mode\en", argv[i]); + close(fd); +} + +fileargs_free(fa); +.Ed +.Sh SEE ALSO +.Xr cap_enter 2 , +.Xr lstat 2 , +.Xr open 2 , +.Xr cap_rights_init 3 , +.Xr err 3 , +.Xr fopen 3 , +.Xr getopt 3 , +.Xr realpath 3 , +.Xr capsicum 4 , +.Xr nv 9 +.Sh HISTORY +The +.Nm +service first appeared in +.Fx 10.3 . +.Sh AUTHORS +.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org +.Sh BUGS +The +.Nm +service is considered experimental and should be thoroughly evaluated +for risks before deploying in production environments. |