diff --git a/lib/libcasper/libcasper/libcasper.3 b/lib/libcasper/libcasper/libcasper.3 index ccd347232777..15f231d7e366 100644 --- a/lib/libcasper/libcasper/libcasper.3 +++ b/lib/libcasper/libcasper/libcasper.3 @@ -1,303 +1,317 @@ .\" Copyright (c) 2013 The FreeBSD Foundation .\" Copyright (c) 2018 Mariusz Zaborski .\" All rights reserved. .\" .\" 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 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 September 6, 2023 +.Dd December 6, 2023 .Dt LIBCASPER 3 .Os .Sh NAME .Nm cap_init , .Nm cap_wrap , .Nm cap_unwrap , .Nm cap_sock , .Nm cap_clone , .Nm cap_close , .Nm cap_limit_get , .Nm cap_limit_set , .Nm cap_send_nvlist , .Nm cap_recv_nvlist , .Nm cap_xfer_nvlist , .Nm cap_service_open .Nd "library for handling application capabilities" .Sh LIBRARY .Lb libcasper .Sh SYNOPSIS .Fd #define WITH_CASPER .In sys/nv.h .In libcasper.h .Ft "cap_channel_t *" .Fn cap_init "void" .Ft "cap_channel_t *" .Fn cap_wrap "int sock" "int flags" .Ft "int" .Fn cap_unwrap "cap_channel_t *chan" "int *flags" .Ft "int" .Fn cap_sock "const cap_channel_t *chan" .Ft "cap_channel_t *" .Fn cap_clone "const cap_channel_t *chan" .Ft "void" .Fn cap_close "cap_channel_t *chan" .Ft "int" .Fn cap_limit_get "const cap_channel_t *chan" "nvlist_t **limitsp" .Ft "int" .Fn cap_limit_set "const cap_channel_t *chan" "nvlist_t *limits" .Ft "int" .Fn cap_send_nvlist "const cap_channel_t *chan" "const nvlist_t *nvl" .Ft "nvlist_t *" .Fn cap_recv_nvlist "const cap_channel_t *chan" .Ft "nvlist_t *" .Fn cap_xfer_nvlist "const cap_channel_t *chan" "nvlist_t *nvl" .Ft "cap_channel_t *" .Fn cap_service_open "const cap_channel_t *chan" "const char *name" .Sh DESCRIPTION The .Nm libcasper library provides for the control of application capabilities through the casper process. .Pp An application capability, represented by the .Vt cap_channel_t type, is a communication channel between the caller and the casper daemon or an instance of one of the daemon's services. A capability to the casper process, obtained with the .Fn cap_init function, allows a program to create capabilities to access the casper daemon's services via the .Fn cap_service_open function. .Pp The .Fn cap_init function instantiates a capability to allow a program to access the casper daemon. -It must be called from a single-threaded context. .Pp The .Fn cap_wrap function creates a .Vt cap_channel_t based on the socket supplied in the call. The function is used when a capability is inherited through the .Xr execve 2 system call, or sent over a .Xr unix 4 domain socket as a file descriptor, and has to be converted into a .Vt cap_channel_t . The .Fa flags argument defines the channel behavior. The supported flags are: .Bl -ohang -offset indent .It CASPER_NO_UNIQ The communication between the process and the casper daemon uses no unique version of nvlist. .El .Pp The .Fn cap_unwrap function returns the .Xr unix 4 domain socket used by the daemon service, and frees the .Vt cap_channel_t structure. .Pp The .Fn cap_clone function returns a clone of the capability passed as its only argument. .Pp The .Fn cap_close function closes, and frees, the given capability. .Pp The .Fn cap_sock function returns the .Xr unix 4 domain socket descriptor associated with the given capability for use with system calls such as: .Xr kevent 2 , .Xr poll 2 , and .Xr select 2 . .Pp The .Fn cap_limit_get function stores the current limits of the given capability in the .Fa limitsp argument. If the function returns .Va 0 and .Dv NULL is stored in the .Fa limitsp argument, there are no limits set. .Pp The .Fn cap_limit_set function sets limits for the given capability. The limits are provided as an .Xr nvlist 9 . The exact format of the limits depends on the service that the capability represents. .Fn cap_limit_set frees the limits passed to the call, whether or not the operation succeeds or fails. .Pp The .Fn cap_send_nvlist function sends the given .Xr nvlist 9 over the given capability. This is a low level interface to communicate with casper services. It is expected that most services will provide a higher level API. .Pp The .Fn cap_recv_nvlist function receives the given .Xr nvlist 9 over the given capability. .Pp The .Fn cap_xfer_nvlist function sends the given .Xr nvlist 9 , destroys it, and receives a new .Xr nvlist 9 in response over the given capability. It does not matter if the function succeeds or fails, the .Xr nvlist 9 given for sending will always be destroyed before the function returns. .Pp The .Fn cap_service_open function opens the casper service named in the call using the casper capability obtained via the .Fn cap_init function. The .Fn cap_service_open function returns a capability that provides access to the opened service. Casper supports the following services in the base system: .Pp .Bl -tag -width "system.random" -compact -offset indent .It system.dns provides libc compatible DNS API .It system.fileargs provides an API for opening files specified on a command line .It system.grp provides a .Xr getgrent 3 compatible API .It system.net provides a libc compatible network API .It system.netdb provides libc compatible network proto API .It system.pwd provides a .Xr getpwent 3 compatible API .It system.sysctl provides a .Xr sysctlbyname 3 compatible API .It system.syslog provides a .Xr syslog 3 compatible API .El +.Pp +.Fn cap_init +must be called from a single-threaded context. +.Fn cap_clone , +.Fn cap_close , +.Fn cap_limit_get , +.Fn cap_limit_set , +.Fn cap_send_nvlist , +.Fn cap_recv_nvlist , +and +.Fn cap_service_open +are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh RETURN VALUES The .Fn cap_clone , .Fn cap_init , .Fn cap_recv_nvlist , .Fn cap_service_open , .Fn cap_wrap and .Fn cap_xfer_nvlist functions return .Dv NULL and set the .Va errno variable on failure. .Pp The .Fn cap_limit_get , .Fn cap_limit_set and .Fn cap_send_nvlist functions return .Dv -1 and set the .Va errno variable on failure. .Pp The .Fn cap_close , .Fn cap_sock and .Fn cap_unwrap functions always succeed. .Sh SEE ALSO .Xr errno 2 , .Xr execve 2 , .Xr kevent 2 , .Xr poll 2 , .Xr select 2 , .Xr cap_dns 3 , .Xr cap_fileargs 3 , .Xr cap_grp 3 , .Xr cap_net 3 , .Xr cap_netdb 3 , .Xr cap_pwd 3 , .Xr cap_sysctl 3 , .Xr cap_syslog 3 , .Xr libcasper_service 3 , .Xr capsicum 4 , .Xr unix 4 , .Xr nv 9 .Sh HISTORY The .Nm libcasper library first appeared in .Fx 10.3 . .Sh AUTHORS The .Nm libcasper library was implemented by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation. The .Nm libcasper new architecture was implemented by .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . diff --git a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 b/lib/libcasper/services/cap_fileargs/cap_fileargs.3 index ef43c26cb3ed..c7ce45c518d1 100644 --- a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 +++ b/lib/libcasper/services/cap_fileargs/cap_fileargs.3 @@ -1,290 +1,302 @@ .\" Copyright (c) 2018 Mariusz Zaborski .\" 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 January 10, 2021 +.Dd December 6, 2023 .Dt CAP_FILEARGS 3 .Os .Sh NAME .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 LIBRARY .Lb libcap_fileargs .Sh SYNOPSIS .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 library is used to simplify Capsicumizing a tools that are using file system. Idea behind the library is that we are passing a remaining .Fa argc and .Fa argv which contains a list of files that should be open for this program. The library will create a service that will serve those files. .Pp The function .Fn fileargs_init create 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 which will not create a service and all files will be prohibited to be opened. The .Fa argc argument contains a number of passed files. The .Fa flags argument limits opened files for either execution or reading and/or writing. The .Fa mode argument tells which what mode file should be created if the .Dv O_CREATE flag is present . For more details of the .Fa flags and .Fa mode arguments see .Xr open 2 . The .Fa rightsp argument contains a list of the capability rights which file should be limited to. For more details of the capability rights see .Xr cap_rights_init 3 . The .Fa operations argument limits the operations that are available using .Nm system.fileargs . .Fa operations is a combination of: .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 is equivalent to .Fn fileargs_init except that the connection to the Casper needs to be provided. .Pp The functions .Fn fileargs_initnv and .Fn fileargs_cinitnv are respectively equivalent to .Fn fileargs_init and .Fn fileargs_cinit expect that all arguments all provided as .Xr nvlist 9 . For details see .Sx LIMITS . .Pp The .Fa fileargs_free close connection to the .Nm system.fileargs service and free are structures. The function handle .Dv NULL argument. .Pp The function .Fn fileargs_lstat is equivalent to .Xr lstat 2 . .Pp The functions .Fn fileargs_open and .Fn fileargs_fopen are respectively equivalent to .Xr open 2 and .Xr fopen 3 expect that all arguments are fetched from the .Va fileargs_t structure. .Pp The function .Fn fileargs_realpath is equivalent to .Xr realpath 3 . +.Pp +.Fn fileargs_open , +.Fn fileargs_lstat , +.Fn fileargs_realpath , +.Fn fileargs_cinitnv , +.Fn fileargs_initnv , +and +.Fn fileargs_fopen +are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh LIMITS This section describe which values and types should be used to pass arguments to the .Fa system.fileargs through the .Fn fileargs_initnv and .Fn fileargs_cinitnv functions. The .Xr nvlist 9 for that functions must contain the following values and types: .Bl -ohang -offset indent .It flags ( NV_TYPE_NUMBER ) The .Va flags limits opened files for either execution or reading and/or writing. .It mode (NV_TYPE_NUMBER) If in the .Va flags argument the .Dv O_CREATE flag was defined the .Xr nvlist 9 must contain the .Va mode . The .Va mode argument tells which what mode file should be created. .It operations (NV_TYPE_NUMBER) The .Va operations limits the usable operations for .Fa system.fileargs . The possible values are explained as .Va operations argument with .Fn fileargs_init . .El .Pp The .Xr nvlist 9 for that functions may contain the following values and types: .Bl -ohang -offset indent .It cap_rights ( NV_TYPE_BINARY ) The .Va cap_rights argument contains a list of the capability rights which file should be limited to. .It ( NV_TYPE_NULL ) Any number of .Dv NV_TYPE_NULL where the name of the element is name of the file which can be opened. .El .Sh EXAMPLES The following example first parse some options and then create the .Nm system.fileargs service with remaining arguments. .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 cap_fileargs service first appeared in .Fx 10.3 . .Sh AUTHORS .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org .Sh BUGS The .Lb cap_fileargs included in .Fx is considered experimental, and should not be deployed in production environments without careful consideration of the risks associated with the use of experimental operating system features. diff --git a/lib/libcasper/services/cap_grp/cap_grp.3 b/lib/libcasper/services/cap_grp/cap_grp.3 index 7c1bf0320e25..9647b1936b0c 100644 --- a/lib/libcasper/services/cap_grp/cap_grp.3 +++ b/lib/libcasper/services/cap_grp/cap_grp.3 @@ -1,231 +1,236 @@ .\" Copyright (c) 2018 Mariusz Zaborski .\" 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 May 5, 2020 +.Dd December 6, 2023 .Dt CAP_GRP 3 .Os .Sh NAME .Nm cap_getgrent , .Nm cap_getgrnam , .Nm cap_getgrgid , .Nm cap_getgrent_r , .Nm cap_getgrnam_r , .Nm cap_getgrgid_r , .Nm cap_setgroupent , .Nm cap_setgrent , .Nm cap_endgrent , .Nm cap_grp_limit_cmds , .Nm cap_grp_limit_fields , .Nm cap_grp_limit_groups .Nd "library for group database operations in capability mode" .Sh LIBRARY .Lb libcap_grp .Sh SYNOPSIS .In sys/nv.h .In libcasper.h .In casper/cap_grp.h .Ft "struct group *" .Fn cap_getgrent "cap_channel_t *chan" .Ft "struct group *" .Fn cap_getgrnam "cap_channel_t *chan" "const char *name" .Ft "struct group *" .Fn cap_getgrgid "cap_channel_t *chan" "gid_t gid" .Ft "int" .Fn cap_getgrent_r "cap_channel_t *chan" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" .Ft "int" .Fn cap_getgrnam_r "cap_channel_t *chan" "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" .Ft int .Fn cap_getgrgid_r "cap_channel_t *chan" "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result" .Ft int .Fn cap_setgroupent "cap_channel_t *chan" "int stayopen" .Ft int .Fn cap_setgrent "cap_channel_t *chan" .Ft void .Fn cap_endgrent "cap_channel_t *chan" .Ft int .Fn cap_grp_limit_cmds "cap_channel_t *chan" "const char * const *cmds" "size_t ncmds" .Ft int .Fn cap_grp_limit_fields "cap_channel_t *chan" "const char * const *fields" "size_t nfields" .Ft int .Fn cap_grp_limit_groups "cap_channel_t *chan" "const char * const *names" "size_t nnames" "const gid_t *gids" "size_t ngids" .Sh DESCRIPTION The functions .Fn cap_getgrent , .Fn cap_getgrnam , .Fn cap_getgrgid , .Fn cap_getgrent_r , .Fn cap_getgrnam_r , .Fn cap_getgrgid_r , .Fn cap_setgroupent , .Fn cap_setgrent , and .Fn cap_endgrent are respectively equivalent to .Xr getgrent 3 , .Xr getgrnam 3 , .Xr getgrgid 3 , .Xr getgrent_r 3 , .Xr getgrnam_r 3 , .Xr getgrgid_r 3 , .Xr setgroupent 3 , .Xr setgrent 3 , and .Xr endgrent 3 except that the connection to the .Nm system.grp service needs to be provided. .Pp The .Fn cap_grp_limit_cmds function limits the functions allowed in the service. The .Fa cmds variable can be set to .Dv getgrent , .Dv getgrnam , .Dv getgrgid , .Dv getgrent_r , .Dv getgrnam_r , .Dv getgrgid_r , .Dv setgroupent , .Dv setgrent , or .Dv endgrent which will allow to use the function associated with the name. The .Fa ncmds variable contains the number of .Fa cmds provided. .Pp The .Fn cap_grp_limit_fields function allows limit fields returned in the structure .Vt group . The .Fa fields variable can be set to .Dv gr_name .Dv gr_passwd .Dv gr_gid or .Dv gr_mem . The field which was set as the limit will be returned, while the rest of the values not set this way will have default values. The .Fa nfields variable contains the number of .Fa fields provided. .Pp The .Fn cap_grp_limit_groups function allows to limit access to groups. The .Fa names variable allows to limit groups by name and the .Fa gids variable by the group number. The .Fa nnames and .Fa ngids variables provide numbers of limited names and gids. +.Pp +All of these functions are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.grp casper service and uses it to get a group name. .Bd -literal cap_channel_t *capcas, *capgrp; const char *cmds[] = { "getgrgid" }; const char *fields[] = { "gr_name" }; const gid_t gid[] = { 1 }; struct group *group; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Enter capability mode sandbox. */ if (cap_enter() < 0 && errno != ENOSYS) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.grp service. */ capgrp = cap_service_open(capcas, "system.grp"); if (capgrp == NULL) err(1, "Unable to open system.grp service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); /* Limit service to one single function. */ if (cap_grp_limit_cmds(capgrp, cmds, nitems(cmds))) err(1, "Unable to limit access to system.grp service"); /* Limit service to one field as we only need name of the group. */ if (cap_grp_limit_fields(capgrp, fields, nitems(fields))) err(1, "Unable to limit access to system.grp service"); /* Limit service to one gid. */ if (cap_grp_limit_groups(capgrp, NULL, 0, gid, nitems(gid))) err(1, "Unable to limit access to system.grp service"); group = cap_getgrgid(capgrp, gid[0]); if (group == NULL) err(1, "Unable to get name of group"); printf("GID %d is associated with name %s.\\n", gid[0], group->gr_name); cap_close(capgrp); .Ed .Sh SEE ALSO .Xr cap_enter 2 , .Xr endgrent 3 , .Xr err 3 , .Xr getgrent 3 , .Xr getgrent_r 3 , .Xr getgrgid 3 , .Xr getgrgid_r 3 , .Xr getgrnam 3 , .Xr getgrnam_r 3 , .Xr setgrent 3 , .Xr setgroupent 3 , .Xr capsicum 4 , .Xr nv 9 .Sh HISTORY The .Nm cap_grp service first appeared in .Fx 10.3 . .Sh AUTHORS The .Nm cap_grp service was implemented by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation. .Pp This manual page was written by .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . diff --git a/lib/libcasper/services/cap_net/cap_net.3 b/lib/libcasper/services/cap_net/cap_net.3 index 534d28c2ef7c..6e525508d3c4 100644 --- a/lib/libcasper/services/cap_net/cap_net.3 +++ b/lib/libcasper/services/cap_net/cap_net.3 @@ -1,283 +1,292 @@ .\" Copyright (c) 2020 Mariusz Zaborski .\" .\" 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 December 5, 2023 +.Dd December 6, 2023 .Dt CAP_NET 3 .Os .Sh NAME .Nm cap_bind , .Nm cap_connect , .Nm cap_getaddrinfo , .Nm cap_gethostbyaddr , .Nm cap_gethostbyname , .Nm cap_gethostbyname2 , .Nm cap_getnameinfo , .Nm cap_net_free , .Nm cap_net_limit , .Nm cap_net_limit_addr2name , .Nm cap_net_limit_addr2name_family , .Nm cap_net_limit_bind , .Nm cap_net_limit_connect , .Nm cap_net_limit_init , .Nm cap_net_limit_name2addr , .Nm cap_net_limit_name2addr_family , .Nd "library for networking in capability mode" .Sh LIBRARY .Lb libcap_net .Sh SYNOPSIS .In sys/nv.h .In libcasper.h .In casper/cap_net.h .Ft int .Fn cap_bind "cap_channel_t *chan" "int s" "const struct sockaddr *addr" "socklen_t addrlen" .Ft int .Fn cap_connect "cap_channel_t *chan" "int s" "const struct sockaddr *name" "socklen_t namelen" .Ft int .Fn cap_getaddrinfo "cap_channel_t *chan" "const char *hostname" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" .Ft int .Fn cap_getnameinfo "cap_channel_t *chan" "const struct sockaddr *sa" "socklen_t salen" "char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" .Ft "struct hostent *" .Fn cap_gethostbyname "const cap_channel_t *chan" "const char *name" .Ft "struct hostent *" .Fn cap_gethostbyname2 "const cap_channel_t *chan" "const char *name" "int af" .Ft "struct hostent *" .Fn cap_gethostbyaddr "const cap_channel_t *chan" "const void *addr" "socklen_t len" "int af" .Ft "cap_net_limit_t *" .Fn cap_net_limit_init "cap_channel_t *chan" "uint64_t mode" .Ft int .Fn cap_net_limit "cap_net_limit_t *limit" .Ft void .Fn cap_net_free "cap_net_limit_t *limit" .Ft "cap_net_limit_t *" .Fn cap_net_limit_addr2name_family "cap_net_limit_t *limit" "int *family" "size_t size" .Ft "cap_net_limit_t *" .Fn cap_net_limit_addr2name "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Ft "cap_net_limit_t *" .Fn cap_net_limit_name2addr_family "cap_net_limit_t *limit" "int *family" "size_t size" .Ft "cap_net_limit_t *" .Fn cap_net_limit_name2addr "cap_net_limit_t *limit" "const char *name" "const char *serv" .Ft "cap_net_limit_t *" .Fn cap_net_limit_connect "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Ft "cap_net_limit_t *" .Fn cap_net_limit_bind "cap_net_limit_t *limit" "const struct sockaddr *sa" "socklen_t salen" .Sh DESCRIPTION The functions .Fn cap_bind , .Fn cap_connect , +.Fn cap_getaddrinfo , +.Fn cap_getnameinfo , .Fn cap_gethostbyname , .Fn cap_gethostbyname2 , -.Fn cap_gethostbyaddr and -.Fn cap_getnameinfo +.Fn cap_gethostbyaddr provide a set of APIs equivalent to .Xr bind 2 , .Xr connect 2 , +.Xr getaddrinfo 3 , +.Xr getnameinfo 3 , .Xr gethostbyname 3 , .Xr gethostbyname2 3 , -.Xr gethostbyaddr 3 and -.Xr getnameinfo 3 +.Xr gethostbyaddr 3 except that a connection to the .Nm system.net service needs to be provided. +.Pp +These functions, as well as +.Fn cap_net_limit , +are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh LIMITS By default, the cap_net capability provides unrestricted access to the network namespace. Applications typically only require access to a small portion of the network namespace: The .Fn cap_net_limit function can be used to restrict access to the network. The .Fn cap_net_limit_init returns an opaque limit handle used to store a list of capabilities. The .Fv mode restricts the functionality of the service. Modes are encoded using the following flags: .Pp .Bd -literal -offset indent -compact CAPNET_ADDR2NAME reverse DNS lookups are allowed with cap_getnameinfo CAPNET_NAME2ADDR name resolution is allowed with cap_getaddrinfo CAPNET_DEPRECATED_ADDR2NAME reverse DNS lookups are allowed with cap_gethostbyaddr CAPNET_DEPRECATED_NAME2ADDR name resolution is allowed with cap_gethostbyname and cap_gethostbyname2 CAPNET_BIND bind syscall is allowed CAPNET_CONNECT connect syscall is allowed CAPNET_CONNECTDNS connect syscall is allowed to the values returned from previous call to the cap_getaddrinfo or cap_gethostbyname .Ed .Pp .Fn cap_net_limit_addr2name_family limits the .Fn cap_getnameinfo and .Fn cap_gethostbyaddr to do reverse DNS lookups to specific family (AF_INET, AF_INET6, etc.) .Pp .Fn cap_net_limit_addr2name limits the .Fn cap_getnameinfo and .Fn cap_gethostbyaddr to do reverse DNS lookups only on those specific structures. .Pp .Fn cap_net_limit_name2addr_family limits the .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 to do the name resolution on specific family (AF_INET, AF_INET6, etc.) .Pp .Fn cap_net_limit_addr2name restricts .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 to a set of domains. .Pp .Fn cap_net_limit_bind limits .Fn cap_bind to bind only on those specific structures. .Pp .Fn cap_net_limit_connect limits .Fn cap_connect to connect only on those specific structures. If the CAPNET_CONNECTDNS is set the limits are extended to the values returned by .Fn cap_getaddrinfo , .Fn cap_gethostbyname and .Fn cap_gethostbyname2 In case of the .Fn cap_getaddrinfo the restriction is strict. In case of the .Fn cap_gethostbyname and .Fn cap_gethostbyname2 any port will be accepted in the .Fn cap_connect function. .Pp The .Fn cap_net_limit will consume and apply the limits. .Pp Once a set of limits is applied, subsequent calls to .Fn cap_net_limit will fail unless the new set is a subset of the current set. .Pp If the .Fn cap_net_limit was not called the rights may be freed using .Fn cap_net_free . Multiple calls to .Fn cap_net_limit_addr2name_family , .Fn cap_net_limit_addr2name , .Fn cap_net_limit_name2addr_family , .Fn cap_net_limit_name2addr , .Fn cap_net_limit_connect , and .Fn cap_net_limit_bind is supported, each call is extending preview capabilities. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.net casper service and uses it to resolve a host and connect to it. .Bd -literal cap_channel_t *capcas, *capnet; cap_net_limit_t *limit; int familylimit, error, s; const char *host = "example.com"; struct addrinfo hints, *res; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Cache NLA for gai_strerror. */ caph_cache_catpages(); /* Enter capability mode sandbox. */ if (caph_enter_casper() < 0) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.net service. */ capnet = cap_service_open(capcas, "system.net"); if (capnet == NULL) err(1, "Unable to open system.net service"); /* Close Casper capability. */ cap_close(capcas); /* Limit system.net to reserve IPv4 addresses, to host example.com . */ limit = cap_net_limit_init(capnet, CAPNET_NAME2ADDR | CAPNET_CONNECTDNS); if (limit == NULL) err(1, "Unable to create limits."); cap_net_limit_name2addr(limit, host, "80"); familylimit = AF_INET; cap_net_limit_name2addr_family(limit, &familylimit, 1); if (cap_net_limit(limit) < 0) err(1, "Unable to apply limits."); /* Find IP addresses for the given host. */ memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_INET; hints.ai_socktype = SOCK_STREAM; error = cap_getaddrinfo(capnet, host, "80", &hints, &res); if (error != 0) errx(1, "cap_getaddrinfo(): %s: %s", host, gai_strerror(error)); s = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s < 0) err(1, "Unable to create socket"); if (cap_connect(capnet, s, res->ai_addr, res->ai_addrlen) < 0) err(1, "Unable to connect to host"); .Ed .Sh SEE ALSO .Xr bind 2 , .Xr cap_enter 2 , .Xr connect 2 , .Xr caph_enter 3 , .Xr err 3 , .Xr gethostbyaddr 3 , .Xr gethostbyname 3 , .Xr gethostbyname2 3 , .Xr getnameinfo 3 , .Xr capsicum 4 , .Xr nv 9 .Sh AUTHORS .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org diff --git a/lib/libcasper/services/cap_netdb/cap_netdb.3 b/lib/libcasper/services/cap_netdb/cap_netdb.3 index 1f08ff275067..1f587c2057e7 100644 --- a/lib/libcasper/services/cap_netdb/cap_netdb.3 +++ b/lib/libcasper/services/cap_netdb/cap_netdb.3 @@ -1,87 +1,91 @@ .\" Copyright (c) 2020 Ryan Moeller .\" .\" 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 September 29, 2022 +.Dd December 6, 2023 .Dt CAP_NETDB 3 .Os .Sh NAME .Nm cap_getprotobyname , .Nd "library for getting network proto entry in capability mode" .Sh LIBRARY .Lb libcap_netdb .Sh SYNOPSIS .In sys/nv.h .In libcasper.h .In casper/cap_netdb.h .Ft "struct protoent *" .Fn cap_getprotobyname "const cap_channel_t *chan" "const char *name" .Sh DESCRIPTION The function .Fn cap_getprotobyname is equivalent to .Xr getprotobyname 3 except that the connection to the .Nm system.netdb service needs to be provided. +It is reentrant but not thread-safe. +That is, it may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.netdb casper service and uses it to look up a protocol by name. .Bd -literal cap_channel_t *capcas, *capnetdb; struct protoent *ent; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Enter capability mode sandbox. */ if (caph_enter() < 0) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.netdb service. */ capnetdb = cap_service_open(capcas, "system.netdb"); if (capnetdb == NULL) err(1, "Unable to open system.netdb service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); ent = cap_getprotobyname(capnetdb, "http"); if (ent == NULL) errx(1, "cap_getprotobyname failed to find http proto"); .Ed .Sh SEE ALSO .Xr cap_enter 2 , .Xr caph_enter 3 , .Xr err 3 , .Xr getprotobyname 3 , .Xr capsicum 4 , .Xr nv 9 .Sh AUTHORS The .Nm cap_netdb service was implemented by .An Ryan Moeller Aq Mt freqlabs@FreeBSD.org . diff --git a/lib/libcasper/services/cap_pwd/cap_pwd.3 b/lib/libcasper/services/cap_pwd/cap_pwd.3 index 7417d177a678..b66a0cd083ba 100644 --- a/lib/libcasper/services/cap_pwd/cap_pwd.3 +++ b/lib/libcasper/services/cap_pwd/cap_pwd.3 @@ -1,237 +1,242 @@ .\" Copyright (c) 2018 Mariusz Zaborski .\" 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 May 5, 2020 +.Dd December 6, 2023 .Dt CAP_PWD 3 .Os .Sh NAME .Nm cap_getpwent , .Nm cap_getpwnam , .Nm cap_getpwuid , .Nm cap_getpwent_r , .Nm cap_getpwnam_r , .Nm cap_getpwuid_r , .Nm cap_setpassent , .Nm cap_setpwent , .Nm cap_endpwent , .Nm cap_pwd_limit_cmds , .Nm cap_pwd_limit_fields , .Nm cap_pwd_limit_users .Nd "library for password database operations in capability mode" .Sh LIBRARY .Lb libcap_pwd .Sh SYNOPSIS .In libcasper.h .In casper/cap_pwd.h .Ft struct passwd * .Fn cap_getpwent "cap_channel_t *chan" .Ft struct passwd * .Fn cap_getpwnam "cap_channel_t *chan" "const char *login" .Ft struct passwd * .Fn cap_getpwuid "cap_channel_t *chan" "uid_t uid" .Ft int .Fn cap_getpwent_r "cap_channel_t *chan" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" .Ft int .Fn cap_getpwnam_r "cap_channel_t *chan" "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" .Ft int .Fn cap_getpwuid_r "cap_channel_t *chan" "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" .Ft int .Fn cap_setpassent "cap_channel_t *chan" "int stayopen" .Ft void .Fn cap_setpwent "cap_channel_t *chan" .Ft void .Fn cap_endpwent "cap_channel_t *chan" .Ft int .Fn cap_pwd_limit_cmds "cap_channel_t *chan" "const char * const *cmds" "size_t ncmds" .Ft int .Fn cap_pwd_limit_fields "cap_channel_t *chan" "const char * const *fields" "size_t nfields" .Ft int .Fn cap_pwd_limit_users "cap_channel_t *chan" "const char * const *names" "size_t nnames" "uid_t *uids" "size_t nuids" .Sh DESCRIPTION The functions .Fn cap_getpwent , .Fn cap_getpwnam , .Fn cap_getpwuid , .Fn cap_getpwent_r , .Fn cap_getpwnam_r , .Fn cap_getpwuid_r , .Fn cap_setpassent , .Fn cap_setpwent , and .Fn cap_endpwent are respectively equivalent to .Xr getpwent 3 , .Xr getpwnam 3 , .Xr getpwuid 3 , .Xr getpwent_r 3 , .Xr getpwnam_r 3 , .Xr getpwuid_r 3 , .Xr setpassent 3 , .Xr setpwent 3 , and .Xr cap_endpwent 3 except that the connection to the .Nm system.pwd service needs to be provided. .Pp The .Fn cap_pwd_limit_cmds function limits the functions allowed in the service. The .Fa cmds variable can be set to .Dv getpwent , .Dv getpwnam , .Dv getpwuid , .Dv getpwent_r , .Dv getpwnam_r , .Dv getpwuid_r , .Dv setpassent , .Dv setpwent , or .Dv endpwent which will allow to use the function associated with the name. The .Fa ncmds variable contains the number of .Fa cmds provided. .Pp The .Fn cap_pwd_limit_fields function allows limit fields returned in the structure .Vt passwd . The .Fa fields variable can be set to .Dv pw_name , .Dv pw_passwd , .Dv pw_uid , .Dv pw_gid , .Dv pw_change , .Dv pw_class , .Dv pw_gecos , .Dv pw_dir , .Dv pw_shell , .Dv pw_expire or .Dv pw_fields The field which was set as the limit will be returned, while the rest of the values not set this way will have default values. The .Fa nfields variable contains the number of .Fa fields provided. .Pp The .Fn cap_pwd_limit_users function allows to limit access to users. The .Fa names variable allows to limit users by name and the .Fa uids variable by the user number. The .Fa nnames and .Fa nuids variables provide numbers of limited names and uids. +.Pp +All of these functions are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.pwd casper service and uses it to get a user name. .Bd -literal cap_channel_t *capcas, *cappwd; const char *cmds[] = { "getpwuid" }; const char *fields[] = { "pw_name" }; uid_t uid[] = { 1 }; struct passwd *passwd; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Enter capability mode sandbox. */ if (cap_enter() < 0 && errno != ENOSYS) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.pwd service. */ cappwd = cap_service_open(capcas, "system.pwd"); if (cappwd == NULL) err(1, "Unable to open system.pwd service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); /* Limit service to one single function. */ if (cap_pwd_limit_cmds(cappwd, cmds, nitems(cmds))) err(1, "Unable to limit access to system.pwd service"); /* Limit service to one field as we only need name of the user. */ if (cap_pwd_limit_fields(cappwd, fields, nitems(fields))) err(1, "Unable to limit access to system.pwd service"); /* Limit service to one uid. */ if (cap_pwd_limit_users(cappwd, NULL, 0, uid, nitems(uid))) err(1, "Unable to limit access to system.pwd service"); passwd = cap_getpwuid(cappwd, uid[0]); if (passwd == NULL) err(1, "Unable to get name of user"); printf("UID %d is associated with name %s.\\n", uid[0], passwd->pw_name); cap_close(cappwd); .Ed .Sh SEE ALSO .Xr cap_enter 2 , .Xr endpwent 3 , .Xr err 3 , .Xr getpwent 3 , .Xr getpwent_r 3 , .Xr getpwnam 3 , .Xr getpwnam_r 3 , .Xr getpwuid 3 , .Xr getpwuid_r 3 , .Xr setpassent 3 , .Xr setpwent 3 , .Xr capsicum 4 , .Xr nv 9 .Sh HISTORY The .Nm cap_pwd service first appeared in .Fx 10.3 . .Sh AUTHORS The .Nm cap_pwd service was implemented by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation. .Pp This manual page was written by .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . diff --git a/lib/libcasper/services/cap_sysctl/cap_sysctl.3 b/lib/libcasper/services/cap_sysctl/cap_sysctl.3 index c007c04aa3b7..2c7a491a1f8b 100644 --- a/lib/libcasper/services/cap_sysctl/cap_sysctl.3 +++ b/lib/libcasper/services/cap_sysctl/cap_sysctl.3 @@ -1,218 +1,227 @@ .\" Copyright (c) 2018 Mariusz Zaborski .\" 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 December 1, 2022 +.Dd December 6, 2023 .Dt CAP_SYSCTL 3 .Os .Sh NAME .Nm cap_sysctl .Nd "library for getting or setting system information in capability mode" .Sh LIBRARY .Lb libcap_sysctl .Sh SYNOPSIS .In libcasper.h .In casper/cap_sysctl.h .Ft int .Fn cap_sysctl "cap_channel_t *chan" "const int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" .Ft int .Fn cap_sysctlbyname "cap_channel_t *chan" "const char *name" "void *oldp" "size_t *oldlenp" "const void *newp" "size_t newlen" .Ft int .Fn cap_sysctlnametomib "cap_channel_t *chan" "const char *name" "int *mibp" "size_t *sizep" .Ft cap_sysctl_limit_t * .Fn cap_sysctl_limit_init "cap_channel_t *chan" .Ft cap_sysctl_limit_t * .Fn cap_sysctl_limit_name "cap_sysctl_limit_t *limit" "const char *name" "int flags" .Ft cap_sysctl_limit_t * .Fn cap_sysctl_limit_mib "cap_sysctl_limit_t *limit" "const int *mibp" "u_int miblen" "int flags" .Ft int .Fn cap_sysctl_limit "cap_sysctl_limit_t *limit" .Sh DESCRIPTION The .Fn cap_sysctl , .Fn cap_sysctlbyname and .Fn cap_sysctlnametomib functions are equivalent to .Xr sysctl 3 , .Xr sysctlbyname 3 and .Xr sysctlnametomib 3 , except that they are implemented by the .Ql system.sysctl .Xr libcasper 3 service and require a corresponding .Xr libcasper 3 capability. +.Pp +All of these functions, with the exceptions of +.Fn cap_sysctl_limit_init +and +.Fn cap_sysctl_limit_mib , +are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh LIMITS By default, the .Nm capability provides unrestricted access to the sysctl namespace. Applications typically only require access to a small number of sysctl variables; the .Fn cap_sysctl_limit interface can be used to restrict the sysctls that can be accessed using the .Nm capability. .Fn cap_sysctl_limit_init returns an opaque limit handle used to store a list of permitted sysctls and access rights. Rights are encoded using the following flags: .Pp .Bd -literal -offset indent -compact CAP_SYSCTL_READ allow reads of the sysctl variable CAP_SYSCTL_WRITE allow writes of the sysctl variable CAP_SYSCTL_RDWR allow reads and writes of the sysctl variable CAP_RECURSIVE permit access to any child of the sysctl variable .Ed .Pp The .Fn cap_sysctl_limit_name function adds the sysctl identified by .Ar name to the limit list, and .Fn cap_sysctl_limit_mib function adds the sysctl identified by .Ar mibp to the limit list. The access rights for the sysctl are specified in the .Ar flags parameter; at least one of .Dv CAP_SYSCTL_READ , .Dv CAP_SYSCTL_WRITE and .Dv CAP_SYSCTL_RDWR must be specified. .Fn cap_sysctl_limit applies a set of sysctl limits to the capability, denying access to sysctl variables not belonging to the set. It consumes the limit handle. After either success or failure, the user must not access the handle again. .Pp Once a set of limits is applied, subsequent calls to .Fn cap_sysctl_limit will fail unless the new set is a subset of the current set. .Pp .Fn cap_sysctlnametomib will succeed so long as the named sysctl variable is present in the limit set, regardless of its access rights. When a sysctl variable name is added to a limit set, its MIB identifier is automatically added to the set. .Sh EXAMPLES The following example first opens a capability to casper, uses this capability to create the .Nm system.sysctl casper service, and then uses the .Nm capability to get the value of .Dv kern.trap_enotcap . .Bd -literal cap_channel_t *capcas, *capsysctl; const char *name = "kern.trap_enotcap"; void *limit; size_t size; bool value; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Enter capability mode sandbox. */ if (cap_enter() < 0 && errno != ENOSYS) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.sysctl service. */ capsysctl = cap_service_open(capcas, "system.sysctl"); if (capsysctl == NULL) err(1, "Unable to open system.sysctl service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); /* Create limit for one MIB with read access only. */ limit = cap_sysctl_limit_init(capsysctl); (void)cap_sysctl_limit_name(limit, name, CAP_SYSCTL_READ); /* Limit system.sysctl. */ if (cap_sysctl_limit(limit) < 0) err(1, "Unable to set limits"); /* Fetch value. */ size = sizeof(value); if (cap_sysctlbyname(capsysctl, name, &value, &size, NULL, 0) < 0) err(1, "Unable to get value of sysctl"); printf("The value of %s is %d.\\n", name, value); cap_close(capsysctl); .Ed .Sh RETURN VALUES .Fn cap_sysctl_limit_init will return a new limit handle on success or .Dv NULL on failure, and set .Va errno . .Fn cap_sysctl_limit_mib and .Fn cap_sysctl_limit_name will return the modified limit handle on success or .Dv NULL on failure and set .Va errno . After failure, the caller must not access the limit handle again. .Fn cap_sysctl_limit will return .Dv -1 on failure and set .Va errno . .Fn cap_sysctl , .Fn cap_sysctlbyname , and .Fn cap_sysctlnametomib have the same return values as their non-capability-mode equivalents as documented in .Xr sysctl 3 . .Sh SEE ALSO .Xr cap_enter 2 , .Xr err 3 , .Xr sysctl 3 , .Xr sysctlbyname 3 , .Xr sysctlnametomib 3 , .Xr capsicum 4 , .Xr nv 9 .Sh HISTORY The .Nm cap_sysctl service first appeared in .Fx 10.3 . .Sh AUTHORS The .Nm cap_sysctl service was implemented by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation. .Pp This manual page was written by .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . diff --git a/lib/libcasper/services/cap_syslog/cap_syslog.3 b/lib/libcasper/services/cap_syslog/cap_syslog.3 index 7e5376c5ca89..4d6463ef3f81 100644 --- a/lib/libcasper/services/cap_syslog/cap_syslog.3 +++ b/lib/libcasper/services/cap_syslog/cap_syslog.3 @@ -1,110 +1,115 @@ .\" Copyright (c) 2018 Mariusz Zaborski .\" 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 May 5, 2020 +.Dd December 6, 2023 .Dt CAP_SYSLOG 3 .Os .Sh NAME .Nm cap_syslog , .Nm cap_vsyslog , .Nm cap_openlog , .Nm cap_closelog , .Nm cap_setlogmask .Nd "library for syslog in capability mode" .Sh LIBRARY .Lb libcap_syslog .Sh SYNOPSIS .In libcasper.h .In casper/cap_syslog.h .Ft void .Fn cap_syslog "cap_channel_t *chan" "int pri" "const char *fmt" "..." .Ft void .Fn cap_vsyslog "cap_channel_t *chan" "int priority" "const char *fmt" "va_list ap" .Ft void .Fn cap_openlog "cap_channel_t *chan" "const char *ident" "int logopt" "int facility" .Ft void .Fn cap_closelog "cap_channel_t *chan" .Ft int .Fn cap_setlogmask "cap_channel_t *chan" "int maskpri" .Sh DESCRIPTION The functions .Fn cap_syslog .Fn cap_vsyslog .Fn cap_openlog .Fn cap_closelog .Fn cap_setlogmask are respectively equivalent to .Xr syslog 3 , .Xr vsyslog 3 , .Xr openlog 3 , .Xr closelog 3 , .Xr setlogmask 3 except that the connection to the .Nm system.syslog service needs to be provided. +.Pp +All of these functions are reentrant but not thread-safe. +That is, they may be called from separate threads only with different +.Vt cap_channel_t +arguments or with synchronization. .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.syslog casper service to log messages. .Bd -literal cap_channel_t *capcas, *capsyslog; /* Open capability to Casper. */ capcas = cap_init(); if (capcas == NULL) err(1, "Unable to contact Casper"); /* Enter capability mode sandbox. */ if (cap_enter() < 0 && errno != ENOSYS) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.syslog service. */ capsyslog = cap_service_open(capcas, "system.syslog"); if (capsyslog == NULL) err(1, "Unable to open system.syslog service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); /* Let's log something. */ cap_syslog(capsyslog, LOG_NOTICE, "System logs from capability mode."); .Ed .Sh SEE ALSO .Xr cap_enter 2 , .Xr closelog 3 , .Xr err 3 , .Xr openlog 3 , .Xr setlogmask 3 , .Xr syslog 3 , .Xr vsyslog 3 , .Xr capsicum 4 , .Xr nv 9 .Sh HISTORY The .Nm cap_syslog service first appeared in .Fx 10.3 . .Sh AUTHORS .An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org