diff --git a/lib/libcasper/libcasper/libcasper.3 b/lib/libcasper/libcasper/libcasper.3 index 149dd49eb1c9..bf678457abeb 100644 --- a/lib/libcasper/libcasper/libcasper.3 +++ b/lib/libcasper/libcasper/libcasper.3 @@ -1,288 +1,289 @@ .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 3, 2021 .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 allows to manage application capabilities through the casper process. .Pp The application capability (represented by the .Vt cap_channel_t type) is a communication channel between the caller and the casper process daemon or an instance of one of its services. A capability to the casper process obtained with the .Fn cap_init function allows to create capabilities to casper's services via the .Fn cap_service_open function. .Pp The .Fn cap_init function opens capability to the casper process. .Pp The .Fn cap_wrap function creates .Vt cap_channel_t based on the given socket. The function is used when capability is inherited through .Xr execve 2 or send over .Xr unix 4 domain socket as a regular file descriptor and has to be represented as .Vt cap_channel_t again. The .Fa flags argument defines the channel behavior. The supported flags are: .Bl -ohang -offset indent .It CASPER_NO_UNIQ The communication between process and casper uses no unique version of nvlist. .El .Pp The .Fn cap_unwrap function is the opposite of the .Fn cap_wrap function. It frees the .Vt cap_channel_t structure and returns .Xr unix 4 domain socket associated with it. .Pp The .Fn cap_clone function clones the given capability. .Pp The .Fn cap_close function closes the given capability. .Pp The .Fn cap_sock function returns .Xr unix 4 domain socket descriptor associated with the given capability for use with system calls like .Xr kevent 2 , .Xr poll 2 and .Xr select 2 . .Pp The .Fn cap_limit_get function stores current limits of the given capability in the .Fa limitsp argument. If the function return .Va 0 and .Dv NULL is stored in .Fa limitsp it means there are no limits set. .Pp The .Fn cap_limit_set function sets limits for the given capability. The limits are provided as a .Xr nvlist 9 . The exact format depends on the service the capability represents. .Fn cap_limit_set frees the limits regardless of whether the operation succeeds or fails. .Pp The .Fn cap_send_nvlist function sends the given .Xr nvlist 9 over the given capability. This is low level interface to communicate with casper services. Most services should provide 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 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 once the function returns. .Pp The .Fn cap_service_open function opens casper service of the given name through casper capability obtained via the .Fn cap_init function. The function returns capability that provides access to opened service. Casper supports the following services in the base system: -.Bl -tag -width "system.random" -compact -offset indent .Pp +.Bl -tag -width "system.random" -compact -offset indent .It system.dns provides DNS libc compatible API .It system.grp provides .Xr getgrent 3 compatible API .It system.net provides network libc compatible API .It system.pwd provides .Xr getpwent 3 compatible API .It system.sysctl provides .Xr sysctlbyname 3 compatible API .It system.syslog provides .Xr syslog 3 compatible API +.El .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_grp 3 , .Xr cap_net 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_dns/cap_dns.3 b/lib/libcasper/services/cap_dns/cap_dns.3 index 104e37f53d86..faa994dc2a6f 100644 --- a/lib/libcasper/services/cap_dns/cap_dns.3 +++ b/lib/libcasper/services/cap_dns/cap_dns.3 @@ -1,242 +1,243 @@ .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 15, 2020 .Dt CAP_DNS 3 .Os .Sh NAME .Nm cap_getaddrinfo , .Nm cap_getnameinfo , .Nm cap_gethostbyname , .Nm cap_gethostbyname2 , .Nm cap_gethostbyaddr , .Nm cap_dns_type_limit , .Nm cap_dns_family_limit .Nd "library for getting network host entry in capability mode" .Sh LIBRARY .Lb libcap_dns .Sh SYNOPSIS .In sys/nv.h .In libcasper.h .In casper/cap_dns.h .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 "int" .Fn cap_dns_type_limit "cap_channel_t *chan" "const char * const *types" "size_t ntypes" .Ft "int" .Fn cap_dns_family_limit "const cap_channel_t *chan" "const int *families" "size_t nfamilies" .Sh DESCRIPTION .Bf -symbolic This service is obsolete and .Xr cap_net 3 should be used instead. The .Fn cap_getaddrinfo , and .Fn cap_getnameinfo , functions are preferred over the .Fn cap_gethostbyname , .Fn cap_gethostbyname2 , and .Fn cap_gethostbyaddr functions. .Ef .Pp The functions .Fn cap_gethostbyname , .Fn cap_gethostbyname2 , .Fn cep_gethostbyaddr and .Fn cap_getnameinfo are respectively equivalent to .Xr gethostbyname 3 , .Xr gethostbyname2 3 , .Xr gethostbyaddr 3 and .Xr getnameinfo 3 except that the connection to the .Nm system.dns service needs to be provided. .Pp The .Fn cap_dns_type_limit function limits the functions allowed in the service. The .Fa types variable can be set to .Dv ADDR2NAME or .Dv NAME2ADDR . See the .Sx LIMITS section for more details. The .Fa ntpyes variable contains the number of .Fa types provided. .Pp The .Fn cap_dns_family_limit functions allows to limit address families. For details see .Sx LIMITS . The .Fa nfamilies variable contains the number of .Fa families provided. .Sh LIMITS The preferred way of setting limits is to use the .Fn cap_dns_type_limit and .Fn cap_dns_family_limit functions, but the limits of service can be set also using .Xr cap_limit_set 3 . The .Xr nvlist 9 for that function can contain the following values and types: .Bl -ohang -offset indent .It type ( NV_TYPE_STRING ) The .Va type can have two values: .Dv ADDR2NAME or .Dv NAME2ADDR . The .Dv ADDR2NAME means that reverse DNS lookups are allowed with .Fn cap_getnameinfo and .Fn cap_gethostbyaddr functions. In case when .Va type is set to .Dv NAME2ADDR the name resolution is allowed with .Fn cap_getaddrinfo , .Fn cap_gethostbyname , and .Fn cap_gethostbyname2 functions. .It family ( NV_TYPE_NUMBER ) The .Va family limits service to one of the address families (e.g. .Dv AF_INET , AF_INET6 , etc.). +.El .Sh EXAMPLES The following example first opens a capability to casper and then uses this capability to create the .Nm system.dns casper service and uses it to resolve an IP address. .Bd -literal cap_channel_t *capcas, *capdns; int familylimit, error; const char *ipstr = "127.0.0.1"; const char *typelimit = "ADDR2NAME"; char hname[NI_MAXHOST]; 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() < 0) err(1, "Unable to enter capability mode"); /* Use Casper capability to create capability to the system.dns service. */ capdns = cap_service_open(capcas, "system.dns"); if (capdns == NULL) err(1, "Unable to open system.dns service"); /* Close Casper capability, we don't need it anymore. */ cap_close(capcas); /* Limit system.dns to reserve IPv4 addresses */ familylimit = AF_INET; if (cap_dns_family_limit(capdns, &familylimit, 1) < 0) err(1, "Unable to limit access to the system.dns service"); /* Convert IP address in C-string to struct sockaddr. */ memset(&hints, 0, sizeof(hints)); hints.ai_family = familylimit; hints.ai_flags = AI_NUMERICHOST; error = cap_getaddrinfo(capdns, ipstr, NULL, &hints, &res); if (error != 0) errx(1, "cap_getaddrinfo(): %s: %s", ipstr, gai_strerror(error)); /* Limit system.dns to reverse DNS lookups. */ if (cap_dns_type_limit(capdns, &typelimit, 1) < 0) err(1, "Unable to limit access to the system.dns service"); /* Find hostname for the given IP address. */ error = cap_getnameinfo(capdns, res->ai_addr, res->ai_addrlen, hname, sizeof(hname), NULL, 0, 0); if (error != 0) errx(1, "cap_getnameinfo(): %s: %s", ipstr, gai_strerror(error)); printf("Name associated with %s is %s.\\n", ipstr, hname); .Ed .Sh SEE ALSO .Xr cap_enter 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 HISTORY The .Nm cap_dns service first appeared in .Fx 10.3 . .Sh AUTHORS The .Nm cap_dns 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_fileargs/cap_fileargs.3 b/lib/libcasper/services/cap_fileargs/cap_fileargs.3 index acf51e4ed62b..a02f58d4b4fa 100644 --- a/lib/libcasper/services/cap_fileargs/cap_fileargs.3 +++ b/lib/libcasper/services/cap_fileargs/cap_fileargs.3 @@ -1,291 +1,292 @@ .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 10, 2021 .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 . .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. -.Sh AUTHORS -.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 cd0b4450fdaf..e74f7dd70d67 100644 --- a/lib/libcasper/services/cap_net/cap_net.3 +++ b/lib/libcasper/services/cap_net/cap_net.3 @@ -1,287 +1,286 @@ .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 15, 2020 .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 -.Pp The functions -.Fn cap_bind, -.Fn cap_connect, +.Fn cap_bind , +.Fn cap_connect , .Fn cap_gethostbyname , .Fn cap_gethostbyname2 , .Fn cap_gethostbyaddr and .Fn cap_getnameinfo are respectively equivalent to .Xr bind 2 , .Xr connect 2 , .Xr gethostbyname 3 , .Xr gethostbyname2 3 , .Xr gethostbyaddr 3 and .Xr getnameinfo 3 except that the connection to the .Nm system.net service needs to be provided. .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: .Fn cap_net_limit interface can be used to restrict access to the network. .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 privies 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 .Fn cap_net_limit applies a set of sysctl limits to the capability, denying access to sysctl variables not belonging to the set. .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 The .Fn cap_net_limit will consume the limits. 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_syslog/cap_syslog.3 b/lib/libcasper/services/cap_syslog/cap_syslog.3 index 33ca6527204e..71c3e790fd97 100644 --- a/lib/libcasper/services/cap_syslog/cap_syslog.3 +++ b/lib/libcasper/services/cap_syslog/cap_syslog.3 @@ -1,112 +1,112 @@ .\" 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. .\" .\" $FreeBSD$ .\" .Dd May 5, 2020 .Dt CAP_SYSLOG 3 .Os .Sh NAME -.Nm cap_syslog -.Nm cap_vsyslog -.Nm cap_openlog -.Nm cap_closelog +.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. .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 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