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