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 5, 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 | |||||
bcr: s/capabilitie/capability/ | |||||
Done Inline Actionsgeting -> getting brueffer: geting -> getting | |||||
.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" | |||||
Done Inline ActionsThe cap_getnameinfo() signature is missing. brueffer: The cap_getnameinfo() signature is missing. | |||||
.Fn cap_getnameinfo "const cap_channel_t *chan" "const void *name" "int namelen" | |||||
.Ft "int" | |||||
Done Inline ActionsThe functions brueffer: The functions | |||||
.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 | |||||
Done Inline ActionsNot sure I understand this sentence correctly; is assume the system.dns connection is required for all four cap_* variants? Maybe something like this? and brueffer: Not sure I understand this sentence correctly; is assume the system.dns connection is required… | |||||
Done Inline ActionsI'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… | |||||
Done Inline ActionsAh! "expect -> except" below then :-) Also "need" -> "needs" brueffer: Ah! "expect -> except" below then :-)
Also "need" -> "needs" | |||||
and | |||||
.Xr getnameinfo 2 | |||||
expect that the connection to the | |||||
.Nm system.dns | |||||
Done Inline Actionss/value/values/ bcr: s/value/values/ | |||||
Done Inline Actionsfallowing -> the following brueffer: fallowing -> the following | |||||
services need to be provided. | |||||
.Pp | |||||
Done Inline Actionsservices -> service brueffer: services -> service | |||||
The | |||||
.Fn cap_dns_type_limit | |||||
Done Inline ActionsProbably .Va instead of .Dv since it's a variable? brueffer: Probably .Va instead of .Dv since it's a variable? | |||||
Done Inline ActionsI'm really not sure about that. oshogbo: I'm really not sure about that.
.Va is an funtion argument
And the "type" here is an value of… | |||||
Done Inline ActionsSounds 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. | |||||
function limits the functions allowed in the service. | |||||
The | |||||
.Fa types | |||||
variable can be set to | |||||
Done Inline Actionsneeds a space between NAME and . brueffer: needs a space between NAME and . | |||||
.Dv ADDR | |||||
Done Inline Actions.Dv ADDR brueffer: .Dv ADDR | |||||
or | |||||
.Dv NAME . | |||||
See the | |||||
.Sx LIMITS | |||||
for more deatls. | |||||
Done Inline Actionsare allowed. brueffer: are allowed. | |||||
bruefferUnsubmitted Done Inline Actions"for more deatls" -> "section for more details" brueffer: "for more deatls" -> "section for more details" | |||||
The | |||||
.Fa ntpyes | |||||
variable contains the number of | |||||
.Fa types | |||||
provided. | |||||
.Pp | |||||
The | |||||
Done Inline Actionsfunction is allowed brueffer: function is allowed | |||||
.Fn cap_dns_family_limit | |||||
functions allows limit address families. | |||||
Done Inline Actionss/on/one/ bcr: s/on/one/ | |||||
Done Inline Actionsfamily -> families brueffer: family -> families | |||||
bruefferUnsubmitted Done Inline Actionsto limit brueffer: to limit | |||||
For details see | |||||
.Sx LIMITS . | |||||
The | |||||
.Fa nfamilies | |||||
Done Inline ActionsI 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… | |||||
Done Inline Actionsa capability brueffer: a capability | |||||
variable contains the number of | |||||
.Fa family | |||||
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 fallowing values and types: | |||||
Done Inline ActionsI would remove "the" here, unless you add "service" after Casper. bcr: I would remove "the" here, unless you add "service" after Casper. | |||||
bruefferUnsubmitted Done Inline Actionsfallowing -> following brueffer: fallowing -> following | |||||
.Bl -ohang -offset indent | |||||
.It type ( NV_TYPE_STRING ) | |||||
The | |||||
.Dv 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 | |||||
.Dv type | |||||
is set to | |||||
.Dv NAME | |||||
the | |||||
.Fn cap_getnameinfo | |||||
function is allowed. | |||||
.It family ( NV_TYPE_NUMBER ) | |||||
The | |||||
.Dv family | |||||
limits service to one of the address families (e.g. | |||||
.Dv AF_INET , AF_INET6 , | |||||
etc.). | |||||
.Sh EXAMPLES | |||||
The following example first opens capability to casper and then uses this | |||||
bruefferUnsubmitted Done Inline Actionsa capability brueffer: a capability | |||||
capability to create a capability to the | |||||
.Nm system.dns | |||||
casper service and uses the latter capability to resolve an IP address. | |||||
bruefferUnsubmitted Not Done Inline ActionsLots 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 ActionsMaybe like that? oshogbo: Maybe like that? | |||||
.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; | |||||
Done Inline ActionsAll four entries above need a space between "3" and "," brueffer: All four entries above need a space between "3" and "," | |||||
/* 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 cap_dns service was implemented by | |||||
.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net | |||||
Done Inline Actions.Nm cap_dns brueffer: .Nm cap_dns | |||||
under sponsorship from the FreeBSD Foundation. | |||||
.Pp | |||||
This manual page was written by | |||||
.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . |
s/capabilitie/capability/