Differential D13762 Diff 37502 lib/libcasper/services/cap_dns/cap_dns.3

Changeset View

Standalone View

lib/libcasper/services/cap_dns/cap_dns.3

This file was added.

				.\" 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 4, 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 geting network host entry in capability mode"
				bruefferUnsubmitted Done Inline Actions geting -> getting brueffer: geting -> getting
				.Sh LIBRARY
				bcrUnsubmitted Done Inline Actions s/capabilitie/capability/ bcr: s/capabilitie/capability/
				.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"
				bruefferUnsubmitted Done Inline Actions The cap_getnameinfo() signature is missing. brueffer: The cap_getnameinfo() signature is missing.
				.Sh DESCRIPTION
				Functions
				bruefferUnsubmitted Done Inline Actions The functions brueffer: 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
				expect that the connection to
				.Nm system.dns
				services need to be provided.
				bruefferUnsubmitted Done Inline Actions Not sure I understand this sentence correctly; is assume the system.dns connection is required for all four cap_* variants? Maybe something like this? and .Xr getnameinfo 2 , and expect that a connection to the .Nm system.dns service is provided. brueffer: Not sure I understand this sentence correctly; is assume the system.dns connection is required…
				oshogboAuthorUnsubmitted Done Inline Actions I'm trying to say that the different between API of the get* and cap_get* are only in the one additional parameter with is connection to the system.dns. oshogbo: I'm trying to say that the different between API of the get* and cap_get* are only in the one…
				bruefferUnsubmitted Done Inline Actions Ah! "expect -> except" below then :-) Also "need" -> "needs" brueffer: Ah! "expect -> except" below then :-) Also "need" -> "needs"
				.Sh LIMITS
				The limits of service can be set using
				.Xr cap_limit_set 3 .
				The nvlist can contain fallowing values and types:
				bruefferUnsubmitted Done Inline Actions fallowing -> the following brueffer: fallowing -> the following
				.Bl -ohang -offset indent
				bcrUnsubmitted Done Inline Actions s/value/values/ bcr: s/value/values/
				.It type ( NV_TYPE_STRING )
				The
				bruefferUnsubmitted Done Inline Actions services -> service brueffer: services -> service
				.Dv type
				bruefferUnsubmitted Done Inline Actions Probably .Va instead of .Dv since it's a variable? brueffer: Probably .Va instead of .Dv since it's a variable?
				oshogboAuthorUnsubmitted Done Inline Actions I'm really not sure about that. .Va is an funtion argument And the "type" here is an value of argument. nvlist_add_type(nvl, "type", "ADDR"); oshogbo: I'm really not sure about that. .Va is an funtion argument And the "type" here is an value of…
				bruefferUnsubmitted Done Inline Actions Sounds like .Va would be OK then. .Dv is more for constants and other explicit values. brueffer: Sounds like .Va would be OK then. .Dv is more for constants and other explicit values.
				can have two values:
				.Dv ADDR
				or
				.Dv NAME.
				bruefferUnsubmitted Done Inline Actions needs a space between NAME and . brueffer: needs a space between NAME and .
				The ADDR means that functions
				bruefferUnsubmitted Done Inline Actions .Dv ADDR brueffer: .Dv ADDR
				.Fn cap_gethostbyname ,
				.Fn cap_gethostbyname2
				and
				.Fn cap_gethostbyaddr
				is allowed.
				bruefferUnsubmitted Done Inline Actions are allowed. brueffer: are allowed.
				In case when
				.Dv type
				bruefferUnsubmitted Done Inline Actions "for more deatls" -> "section for more details" brueffer: "for more deatls" -> "section for more details"
				is set to
				.Dv NAME
				the
				.Fn cap_getnameinfo
				is allowed.
				bruefferUnsubmitted Done Inline Actions function is allowed brueffer: function is allowed
				.It family ( NV_TYPE_NUMBER )
				The family limits service to one of the address family (e.g.
				bruefferUnsubmitted Done Inline Actions family -> families brueffer: family -> families
				.Dv AF_INET , AF_INET6 ,
				bcrUnsubmitted Done Inline Actions s/on/one/ bcr: s/on/one/
				etc.).
				bruefferUnsubmitted Done Inline Actions to limit brueffer: to limit
				.Sh EXAMPLES
				The following example first opens capability to casper and then uses this
				bruefferUnsubmitted Done Inline Actions a capability brueffer: a capability
				capability to create a new capability to the
				bcrUnsubmitted Done Inline Actions I would remove the "the" here and rewrite it to have it read: "The following example first opens capability to casper and then uses this capability to create a new capability to the system.dns casper service and uses the latter capability to resolve an IP address. bcr: I would remove the "the" here and rewrite it to have it read: "The following example first…
				.Nm system.dns
				casper service and uses the latter capability to resolve an IP address.
				.Bd -literal
				cap_channel_t capcas, capdns;
				nvlist_t *limits;
				const char *ipstr = "127.0.0.1";
				struct in_addr ip;
				struct hostent *hp;

				/* Open capability to Casper. */
				capcas = cap_init();
				bcrUnsubmitted Done Inline Actions I would remove "the" here, unless you add "service" after Casper. bcr: I would remove "the" here, unless you add "service" after Casper.
				if (capcas == NULL)
				bruefferUnsubmitted Done Inline Actions fallowing -> following brueffer: fallowing -> following
				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 and IPv4 addresses. */
				limits = nvlist_create(0);
				nvlist_add_string(limits, "type", "ADDR");
				nvlist_add_number(limits, "family", (uint64_t)AF_INET);
				if (cap_limit_set(capdns, limits) < 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);
				bruefferUnsubmitted Done Inline Actions a capability brueffer: a capability
				.Ed
				.Sh SEE ALSO
				.Xr cap_enter 2 ,
				bruefferUnsubmitted Not Done Inline Actions Lots of capabilities in one sentence :-) I'm not sure how to make this clearer though... brueffer: Lots of capabilities in one sentence :-) I'm not sure how to make this clearer though...
				oshogboAuthorUnsubmitted Not Done Inline Actions Maybe like that? oshogbo: Maybe like that?
				.Xr err 3 ,
				.Xr gethostbyaddr 3,
				.Xr gethostbyname 3,
				.Xr gethostbyname2 3,
				.Xr getnameinfo 3,
				bruefferUnsubmitted Done Inline Actions All four entries above need a space between "3" and "," brueffer: All four entries above need a space between "3" and ","
				.Xr nv 3 ,
				.Xr capsicum 4
				.Sh AUTHORS
				The 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 .
				bruefferUnsubmitted Done Inline Actions .Nm cap_dns brueffer: .Nm cap_dns