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.Dd December 6, 2023
26.Dt CAP_FILEARGS 3
27.Os
28.Sh NAME
29.Nm fileargs_cinit ,
30.Nm fileargs_cinitnv ,
31.Nm fileargs_init ,
32.Nm fileargs_initnv ,
33.Nm fileargs_free ,
34.Nm fileargs_lstat ,
35.Nm fileargs_open ,
36.Nm fileargs_fopen
37.Nd "library for handling files in capability mode"
38.Sh LIBRARY
39.Lb libcap_fileargs
40.Sh SYNOPSIS
41.In sys/nv.h
42.In libcasper.h
43.In casper/cap_fileargs.h
44.Ft "fileargs_t *"
45.Fn fileargs_init "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
46.Ft "fileargs_t *"
47.Fn fileargs_cinit "cap_channel_t *cas" "int argc" "char *argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
48.Ft "fileargs_t *"
49.Fn fileargs_cinitnv "cap_channel_t *cas" "nvlist_t *limits"
50.Ft "fileargs_t *"
51.Fn fileargs_initnv "nvlist_t *limits"
52.Ft "void"
53.Fn fileargs_free "fileargs_t *fa"
54.Ft "int"
55.Fn fileargs_lstat "fileargs_t *fa" "const char *path" "struct stat *sb"
56.Ft "int"
57.Fn fileargs_open "fileargs_t *fa" "const char *name"
58.Ft "FILE *"
59.Fn fileargs_fopen "fileargs_t *fa" "const char *name" "const char *mode"
60.Ft "char *"
61.Fn fileargs_realpath "fileargs_t *fa" "const char *pathname" "char *reserved_path"
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.It FA_REALPATH
119Allow
120.Fn fileargs_realpath .
121.El
122.Pp
123The function
124.Fn fileargs_cinit
125is equivalent to
126.Fn fileargs_init
127except that the connection to the Casper needs to be provided.
128.Pp
129The functions
130.Fn fileargs_initnv
131and
132.Fn fileargs_cinitnv
133are respectively equivalent to
134.Fn fileargs_init
135and
136.Fn fileargs_cinit
137expect that all arguments all provided as
138.Xr nvlist 9 .
139For details see
140.Sx LIMITS .
141.Pp
142The
143.Fa fileargs_free
144close connection to the
145.Nm system.fileargs
146service and free are structures.
147The function handle
148.Dv NULL
149argument.
150.Pp
151The function
152.Fn fileargs_lstat
153is equivalent to
154.Xr lstat 2 .
155.Pp
156The functions
157.Fn fileargs_open
158and
159.Fn fileargs_fopen
160are respectively equivalent to
161.Xr open 2
162and
163.Xr fopen 3
164expect that all arguments are fetched from the
165.Va fileargs_t
166structure.
167.Pp
168The function
169.Fn fileargs_realpath
170is equivalent to
171.Xr realpath 3 .
172.Pp
173.Fn fileargs_open ,
174.Fn fileargs_lstat ,
175.Fn fileargs_realpath ,
176.Fn fileargs_cinitnv ,
177.Fn fileargs_initnv ,
178and
179.Fn fileargs_fopen
180are reentrant but not thread-safe.
181That is, they may be called from separate threads only with different
182.Vt cap_channel_t
183arguments or with synchronization.
184.Sh LIMITS
185This section describe which values and types should be used to pass arguments to the
186.Fa system.fileargs
187through the
188.Fn fileargs_initnv
189and
190.Fn fileargs_cinitnv
191functions.
192The
193.Xr nvlist 9
194for that functions must contain the following values and types:
195.Bl -ohang -offset indent
196.It flags ( NV_TYPE_NUMBER )
197The
198.Va flags
199limits opened files for either execution or reading and/or writing.
200.It mode (NV_TYPE_NUMBER)
201If in the
202.Va flags
203argument the
204.Dv O_CREATE
205flag was defined the
206.Xr nvlist 9
207must contain the
208.Va mode .
209The
210.Va mode
211argument tells which what mode file should be created.
212.It operations (NV_TYPE_NUMBER)
213The
214.Va operations
215limits the usable operations for
216.Fa system.fileargs .
217The possible values are explained as
218.Va operations
219argument with
220.Fn fileargs_init .
221.El
222.Pp
223The
224.Xr nvlist 9
225for that functions may contain the following values and types:
226.Bl -ohang -offset indent
227.It cap_rights ( NV_TYPE_BINARY )
228The
229.Va cap_rights
230argument contains a list of the capability rights which file should be limited to.
231.It ( NV_TYPE_NULL )
232Any number of
233.Dv NV_TYPE_NULL
234where the name of the element is name of the file which can be opened.
235.El
236.Sh EXAMPLES
237The following example first parse some options and then create the
238.Nm system.fileargs
239service with remaining arguments.
240.Bd -literal
241int ch, fd, i;
242cap_rights_t rights;
243fileargs_t *fa;
244
245while ((ch = getopt(argc, argv, "h")) != -1) {
246	switch (ch) {
247		case 'h':
248		default:
249			usage();
250	}
251}
252
253argc -= optind;
254argv += optind;
255
256/* Create capability to the system.fileargs service. */
257fa = fileargs_init(argc, argv, O_RDONLY, 0,
258    cap_rights_init(&rights, CAP_READ), FA_OPEN);
259if (fa == NULL)
260	err(1, "unable to open system.fileargs service");
261
262/* Enter capability mode sandbox. */
263if (cap_enter() < 0 && errno != ENOSYS)
264	err(1, "unable to enter capability mode");
265
266/* Open files. */
267for (i = 0; i < argc; i++) {
268	fd = fileargs_open(fa, argv[i]);
269	if (fd < 0)
270		err(1, "unable to open file %s", argv[i]);
271	printf("File %s opened in capability mode\en", argv[i]);
272	close(fd);
273}
274
275fileargs_free(fa);
276.Ed
277.Sh SEE ALSO
278.Xr cap_enter 2 ,
279.Xr lstat 2 ,
280.Xr open 2 ,
281.Xr cap_rights_init 3 ,
282.Xr err 3 ,
283.Xr fopen 3 ,
284.Xr getopt 3 ,
285.Xr realpath 3 ,
286.Xr capsicum 4 ,
287.Xr nv 9
288.Sh HISTORY
289The
290.Nm cap_fileargs
291service first appeared in
292.Fx 10.3 .
293.Sh AUTHORS
294.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org
295.Sh BUGS
296The
297.Lb cap_fileargs
298included in
299.Fx
300is considered experimental, and should not be deployed in production
301environments without careful consideration of the risks associated with
302the use of experimental operating system features.
303