1.\" Copyright (c) 2018 Mariusz Zaborski <oshogbo@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd November 12, 2018
28.Dt CAP_FILEARGS 3
29.Os
30.Sh NAME
31.Nm fileargs_cinit ,
32.Nm fileargs_cinitnv ,
33.Nm fileargs_init ,
34.Nm fileargs_initnv ,
35.Nm fileargs_free ,
36.Nm fileargs_open ,
37.Nm fileargs_fopen
38.Nd "library for handling files in capability mode"
39.Sh LIBRARY
40.Lb libcap_fileargs
41.Sh SYNOPSIS
42.In sys/nv.h
43.In libcasper.h
44.In casper/cap_fileargs.h
45.Ft "fileargs_t *"
46.Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp"
47.Ft "fileargs_t *"
48.Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp"
49.Ft "fileargs_t *"
50.Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits"
51.Ft "fileargs_t *"
52.Fn fileargs_initnv "nvlist_t *limits"
53.Ft "void"
54.Fn fileargs_free "fileargs_t *fa"
55.Ft "int"
56.Fn fileargs_open "fileargs_t *fa" "const char *name"
57.Ft "FILE *"
58.Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode"
59.Sh DESCRIPTION
60The library is used to simplify Capsicumizing a tools that are using file system.
61Idea behind the library is that we are passing a remaining
62.Fa argc
63and
64.Fa argv
65which contains a list of files that should be open for this program.
66The library will create a service that will serve those files.
67.Pp
68The function
69.Fn fileargs_init
70create a service to the
71.Nm system.fileargs .
72The
73.Fa argv
74contains a list of files that should be opened.
75The argument can be set to
76.Dv NULL
77which will not create a service and all files will be prohibited to be opened.
78The
79.Fa argc
80argument contains a number of passed files.
81The
82.Fa flags
83argument limits opened files for either execution or reading and/or writing.
84The
85.Fa mode
86argument tells which what mode file should be created if the
87.Dv O_CREATE
88flag is present .
89For more details of the
90.Fa flags
91and
92.Fa mode
93arguments see
94.Xr open 2 .
95The
96.Fa rightsp
97argument contains a list of the capability rights which file should be limited to.
98For more details of the capability rights see
99.Xr cap_rights_init 3 .
100.Pp
101The function
102.Fn fileargs_cinit
103is equivalent to
104.Fn fileargs_init
105except that the connection to the Casper needs to be provided.
106.Pp
107The functions
108.Fn fileargs_ininv
109and
110.Fn fileargs_cininv
111are respectively equivalent to
112.Fn fileargs_init
113and
114.Fn fileargs_cinit
115expect that all arguments all provided as
116.Xr nvlist 9 .
117For details see
118.Sx LIMITS .
119.Pp
120The
121.Fa fileargs_free
122close connection to the
123.Nm system.filerags
124service and free are structures.
125The function handle
126.Dv NULL
127argument.
128.Pp
129The functions
130.Fn fileargs_open
131and
132.Fn fileargs_fopen
133are respectively equivalent to
134.Xr open 2
135and
136.Xr fopen 3
137expect that all arguments are fetched from the
138.Va fileargs_t
139structure.
140.Sh LIMITS
141This section describe which values and types should be used to pass arguments to the
142.Fa system.filerags
143through the
144.Fn fileargs_ininv
145and
146.Fn fileargs_cinit
147functions.
148The
149.Xr nvlist 9
150for that functions must contain the following values and types:
151.Bl -ohang -offset indent
152.It flags ( NV_TYPE_NUMBER )
153The
154.Va flags
155limits opened files for either execution or reading and/or writing.
156.It mode (NV_TYPE_NUMBER)
157If in the
158.Va flags
159argument the
160.Dv O_CREATE
161flag was defined the
162.Xr nvlist 9
163must contain the
164.Va mode .
165The
166.Va mode
167argument tells which what mode file should be created.
168.El
169.Pp
170The
171.Xr nvlist 9
172for that functions may contain the following values and types:
173.Bl -ohang -offset indent
174.It cap_rights ( NV_TYPE_BINARY )
175The
176.Va cap_rights
177argument contains a list of the capability rights which file should be limited to.
178.It ( NV_TYPE_NULL )
179Any number of
180.Dv NV_TYPE_NULL
181where the name of the element is name of the file which can be opened.
182.Sh EXAMPLES
183The following example first parse some options and then create the
184.Nm system.filerags
185service with remaining arguments.
186.Bd -literal
187int ch, fd, i;
188cap_rights_t rights;
189fileargs_t *fa;
190
191while ((ch = getopt(argc, argv, "h")) != -1) {
192	switch (ch) {
193		case 'h':
194		default:
195			usage();
196	}
197}
198
199argc -= optind;
200argv += optind;
201
202/* Create capability to the system.fileargs service. */
203fa = fileargs_init(argc, argv, O_RDONLY, 0,
204    cap_rights_init(&rights, CAP_READ));
205if (fa == NULL)
206	err(1, "unable to open system.fileargs service");
207
208/* Enter capability mode sandbox. */
209if (cap_enter() < 0 && errno != ENOSYS)
210	err(1, "unable to enter capability mode");
211
212/* Open files. */
213for (i = 0; i < argc; i++) {
214	fd = fileargs_open(fa, argv[i]);
215	if (fd < 0)
216		err(1, "unable to open file %s", argv[i]);
217	printf("File %s opened in capability mode\n", argv[i]);
218	close(fd);
219}
220
221fileargs_free(fa);
222.Ed
223.Sh SEE ALSO
224.Xr cap_enter 2 ,
225.Xr open 2 ,
226.Xr cap_rights_init 3 ,
227.Xr err 3 ,
228.Xr fopen 3,
229.Xr getopt 3,
230.Xr capsicum 4 ,
231.Xr nv 9
232.Sh BUGS
233The
234.Lb cap_fileargs
235included in
236.Fx
237is considered experimental, and should not be deployed in production
238environments without careful consideration of the risks associated with
239the use of experimental operating system features.
240.Sh AUTHORS
241.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
242