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 April 17, 2019
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_lstat ,
37.Nm fileargs_open ,
38.Nm fileargs_fopen
39.Nd "library for handling files in capability mode"
40.Sh LIBRARY
41.Lb libcap_fileargs
42.Sh SYNOPSIS
43.In sys/nv.h
44.In libcasper.h
45.In casper/cap_fileargs.h
46.Ft "fileargs_t *"
47.Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
48.Ft "fileargs_t *"
49.Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
50.Ft "fileargs_t *"
51.Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits"
52.Ft "fileargs_t *"
53.Fn fileargs_initnv "nvlist_t *limits"
54.Ft "void"
55.Fn fileargs_free "fileargs_t *fa"
56.Ft "int"
57.Fn fileargs_lstat "fileargs_t *fa" "const char *path" "struct stat *sb"
58.Ft "int"
59.Fn fileargs_open "fileargs_t *fa" "const char *name"
60.Ft "FILE *"
61.Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode"
62.Sh DESCRIPTION
63The library is used to simplify Capsicumizing a tools that are using file system.
64Idea behind the library is that we are passing a remaining
65.Fa argc
66and
67.Fa argv
68which contains a list of files that should be open for this program.
69The library will create a service that will serve those files.
70.Pp
71The function
72.Fn fileargs_init
73create a service to the
74.Nm system.fileargs .
75The
76.Fa argv
77contains a list of files that should be opened.
78The argument can be set to
79.Dv NULL
80which will not create a service and all files will be prohibited to be opened.
81The
82.Fa argc
83argument contains a number of passed files.
84The
85.Fa flags
86argument limits opened files for either execution or reading and/or writing.
87The
88.Fa mode
89argument tells which what mode file should be created if the
90.Dv O_CREATE
91flag is present .
92For more details of the
93.Fa flags
94and
95.Fa mode
96arguments see
97.Xr open 2 .
98The
99.Fa rightsp
100argument contains a list of the capability rights which file should be limited to.
101For more details of the capability rights see
102.Xr cap_rights_init 3 .
103The
104.Fa operations
105argument limits the operations that are available using
106.Nm system.fileargs .
107.Fa operations
108is a combination of:
109.Bl -ohang -offset indent
110.It FA_OPEN
111Allow
112.Fn fileargs_open
113and
114.Fn fileargs_fopen .
115.It FA_LSTAT
116Allow
117.Fn fileargs_lstat .
118.El
119.Pp
120The function
121.Fn fileargs_cinit
122is equivalent to
123.Fn fileargs_init
124except that the connection to the Casper needs to be provided.
125.Pp
126The functions
127.Fn fileargs_initnv
128and
129.Fn fileargs_cinitnv
130are respectively equivalent to
131.Fn fileargs_init
132and
133.Fn fileargs_cinit
134expect that all arguments all provided as
135.Xr nvlist 9 .
136For details see
137.Sx LIMITS .
138.Pp
139The
140.Fa fileargs_free
141close connection to the
142.Nm system.fileargs
143service and free are structures.
144The function handle
145.Dv NULL
146argument.
147.Pp
148The function
149.Fn fileargs_lstat
150is equivalent to
151.Xr lstat 2 .
152.Pp
153The functions
154.Fn fileargs_open
155and
156.Fn fileargs_fopen
157are respectively equivalent to
158.Xr open 2
159and
160.Xr fopen 3
161expect that all arguments are fetched from the
162.Va fileargs_t
163structure.
164.Sh LIMITS
165This section describe which values and types should be used to pass arguments to the
166.Fa system.fileargs
167through the
168.Fn fileargs_initnv
169and
170.Fn fileargs_cinitnv
171functions.
172The
173.Xr nvlist 9
174for that functions must contain the following values and types:
175.Bl -ohang -offset indent
176.It flags ( NV_TYPE_NUMBER )
177The
178.Va flags
179limits opened files for either execution or reading and/or writing.
180.It mode (NV_TYPE_NUMBER)
181If in the
182.Va flags
183argument the
184.Dv O_CREATE
185flag was defined the
186.Xr nvlist 9
187must contain the
188.Va mode .
189The
190.Va mode
191argument tells which what mode file should be created.
192.It operations (NV_TYPE_NUMBER)
193The
194.Va operations
195limits the usable operations for
196.Fa system.fileargs .
197The possible values are explained as
198.Va operations
199argument with
200.Fn fileargs_init .
201.El
202.Pp
203The
204.Xr nvlist 9
205for that functions may contain the following values and types:
206.Bl -ohang -offset indent
207.It cap_rights ( NV_TYPE_BINARY )
208The
209.Va cap_rights
210argument contains a list of the capability rights which file should be limited to.
211.It ( NV_TYPE_NULL )
212Any number of
213.Dv NV_TYPE_NULL
214where the name of the element is name of the file which can be opened.
215.Sh EXAMPLES
216The following example first parse some options and then create the
217.Nm system.fileargs
218service with remaining arguments.
219.Bd -literal
220int ch, fd, i;
221cap_rights_t rights;
222fileargs_t *fa;
223
224while ((ch = getopt(argc, argv, "h")) != -1) {
225	switch (ch) {
226		case 'h':
227		default:
228			usage();
229	}
230}
231
232argc -= optind;
233argv += optind;
234
235/* Create capability to the system.fileargs service. */
236fa = fileargs_init(argc, argv, O_RDONLY, 0,
237    cap_rights_init(&rights, CAP_READ), FA_OPEN);
238if (fa == NULL)
239	err(1, "unable to open system.fileargs service");
240
241/* Enter capability mode sandbox. */
242if (cap_enter() < 0 && errno != ENOSYS)
243	err(1, "unable to enter capability mode");
244
245/* Open files. */
246for (i = 0; i < argc; i++) {
247	fd = fileargs_open(fa, argv[i]);
248	if (fd < 0)
249		err(1, "unable to open file %s", argv[i]);
250	printf("File %s opened in capability mode\en", argv[i]);
251	close(fd);
252}
253
254fileargs_free(fa);
255.Ed
256.Sh SEE ALSO
257.Xr cap_enter 2 ,
258.Xr lstat 2 ,
259.Xr open 2 ,
260.Xr cap_rights_init 3 ,
261.Xr err 3 ,
262.Xr fopen 3 ,
263.Xr getopt 3 ,
264.Xr capsicum 4 ,
265.Xr nv 9
266.Sh BUGS
267The
268.Lb cap_fileargs
269included in
270.Fx
271is considered experimental, and should not be deployed in production
272environments without careful consideration of the risks associated with
273the use of experimental operating system features.
274.Sh AUTHORS
275.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
276