Document the DNS Casper service.
Reviewed by: brueffer@, bcr@ Differential Revision: https://reviews.freebsd.org/D13762
This commit is contained in:
oshogbo
parent
fa15b01717
commit
ffc175f780
@ -24,4 +24,14 @@ CFLAGS+=-I${.CURDIR}
|
||||
HAS_TESTS=
|
||||
SUBDIR.${MK_TESTS}+= tests
|
||||
|
||||
MAN+= cap_dns.3
|
||||
|
||||
MLINKS+=cap_dns.3 libcap_dns.3
|
||||
MLINKS+=cap_dns.3 cap_gethostbyname.3
|
||||
MLINKS+=cap_dns.3 cap_gethostbyname2.3
|
||||
MLINKS+=cap_dns.3 cap_gethostbyaddr.3
|
||||
MLINKS+=cap_dns.3 cap_getnameinfo.3
|
||||
MLINKS+=cap_dns.3 cap_dns_type_limit.3
|
||||
MLINKS+=cap_dns.3 cap_dns_family_limit.3
|
||||
|
||||
.include <bsd.lib.mk>
|
||||
|
||||
205
lib/libcasper/services/cap_dns/cap_dns.3
Normal file
205
lib/libcasper/services/cap_dns/cap_dns.3
Normal file
@ -0,0 +1,205 @@
|
||||
.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 8, 2018
|
||||
.Dt CAP_DNS 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm cap_gethostbyname ,
|
||||
.Nm cap_gethostbyname2 ,
|
||||
.Nm cap_gethostbyaddr ,
|
||||
.Nm cap_getnameinfo ,
|
||||
.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 "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_getnameinfo "const cap_channel_t *chan" "const void *name" "int namelen"
|
||||
.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
|
||||
The functions
|
||||
.Fn cap_gethostbyname ,
|
||||
.Fn cap_gethostbyname2 ,
|
||||
.Fn cep_gethostbyaddr
|
||||
and
|
||||
.Xr cap_getnameinfo
|
||||
are respectively equivalent to
|
||||
.Xr gethostbyname 2 ,
|
||||
.Xr gethostbyname2 2 ,
|
||||
.Xr gethostbyaddr 2
|
||||
and
|
||||
.Xr getnameinfo 2
|
||||
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 ADDR
|
||||
or
|
||||
.Dv NAME .
|
||||
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 nvlist 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 ADDR
|
||||
or
|
||||
.Dv NAME .
|
||||
The
|
||||
.Dv ADDR
|
||||
means that functions
|
||||
.Fn cap_gethostbyname ,
|
||||
.Fn cap_gethostbyname2
|
||||
and
|
||||
.Fn cap_gethostbyaddr
|
||||
are allowed.
|
||||
In case when
|
||||
.Va type
|
||||
is set to
|
||||
.Dv NAME
|
||||
the
|
||||
.Fn cap_getnameinfo
|
||||
function is allowed.
|
||||
.It family ( NV_TYPE_NUMBER )
|
||||
The
|
||||
.Va family
|
||||
limits service to one of the address families (e.g.
|
||||
.Dv AF_INET , AF_INET6 ,
|
||||
etc.).
|
||||
.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;
|
||||
const char *typelimit = "ADDR";
|
||||
int familylimit;
|
||||
const char *ipstr = "127.0.0.1";
|
||||
struct in_addr ip;
|
||||
struct hostent *hp;
|
||||
|
||||
/* 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.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 reverse DNS lookups. */
|
||||
if (cap_dns_type_limit(capdns, &typelimit, 1) < 0)
|
||||
err(1, "Unable to limit access to the system.dns service");
|
||||
|
||||
/* 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 in_addr. */
|
||||
if (!inet_aton(ipstr, &ip))
|
||||
errx(1, "Unable to parse IP address %s.", ipstr);
|
||||
|
||||
/* Find hostname for the given IP address. */
|
||||
hp = cap_gethostbyaddr(capdns, (const void *)&ip, sizeof(ip), AF_INET);
|
||||
if (hp == NULL)
|
||||
errx(1, "No name associated with %s.", ipstr);
|
||||
|
||||
printf("Name associated with %s is %s.\\n", ipstr, hp->h_name);
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr cap_enter 2 ,
|
||||
.Xr err 3 ,
|
||||
.Xr gethostbyaddr 3 ,
|
||||
.Xr gethostbyname 3 ,
|
||||
.Xr gethostbyname2 3 ,
|
||||
.Xr getnameinfo 3,
|
||||
.Xr nv 3 ,
|
||||
.Xr capsicum 4
|
||||
.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 .
|
||||
Loading…
x
Reference in New Issue
Block a user