diff options
Diffstat (limited to 'static/freebsd/man3/cap_net.3')
| -rw-r--r-- | static/freebsd/man3/cap_net.3 | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/static/freebsd/man3/cap_net.3 b/static/freebsd/man3/cap_net.3 new file mode 100644 index 00000000..e322222e --- /dev/null +++ b/static/freebsd/man3/cap_net.3 @@ -0,0 +1,292 @@ +.\" Copyright (c) 2020 Mariusz Zaborski <oshogbo@FreeBSD.org> +.\" +.\" 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 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 , +and +.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 , +and +.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 +.Fa 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 |