Differential D19548 Diff 56289 head/lib/libcasper/services/cap_fileargs/cap_fileargs.3

Changeset View

Standalone View

head/lib/libcasper/services/cap_fileargs/cap_fileargs.3

Show All 18 Lines
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)		.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT		.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY		.\" 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		.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.		.\" SUCH DAMAGE.
.\"		.\"
.\" $FreeBSD$		.\" $FreeBSD$
.\"		.\"
.Dd November 12, 2018		.Dd April 17, 2019
.Dt CAP_FILEARGS 3		.Dt CAP_FILEARGS 3
.Os		.Os
.Sh NAME		.Sh NAME
.Nm fileargs_cinit ,		.Nm fileargs_cinit ,
.Nm fileargs_cinitnv ,		.Nm fileargs_cinitnv ,
.Nm fileargs_init ,		.Nm fileargs_init ,
.Nm fileargs_initnv ,		.Nm fileargs_initnv ,
.Nm fileargs_free ,		.Nm fileargs_free ,
		.Nm fileargs_lstat ,
.Nm fileargs_open ,		.Nm fileargs_open ,
.Nm fileargs_fopen		.Nm fileargs_fopen
.Nd "library for handling files in capability mode"		.Nd "library for handling files in capability mode"
.Sh LIBRARY		.Sh LIBRARY
.Lb libcap_fileargs		.Lb libcap_fileargs
.Sh SYNOPSIS		.Sh SYNOPSIS
.In sys/nv.h		.In sys/nv.h
.In libcasper.h		.In libcasper.h
.In casper/cap_fileargs.h		.In casper/cap_fileargs.h
.Ft "fileargs_t *"		.Ft "fileargs_t *"
.Fn fileargs_init "int argc" "char argv[]" "int flags" "mode_t mode" "cap_rights_t rightsp"		.Fn fileargs_init "int argc" "char argv[]" "int flags" "mode_t mode" "cap_rights_t rightsp" "int operations"
.Ft "fileargs_t *"		.Ft "fileargs_t *"
.Fn fileargs_cinit "cap_channel_t cas" "int argc" "char argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp"		.Fn fileargs_cinit "cap_channel_t cas" "int argc" "char argv[]" "int flags" "mode_t mode" "cap_rights_t *rightsp" "int operations"
.Ft "fileargs_t *"		.Ft "fileargs_t *"
.Fn fileargs_cinitnv "cap_channel_t cas" "nvlist_t limits"		.Fn fileargs_cinitnv "cap_channel_t cas" "nvlist_t limits"
.Ft "fileargs_t *"		.Ft "fileargs_t *"
.Fn fileargs_initnv "nvlist_t *limits"		.Fn fileargs_initnv "nvlist_t *limits"
.Ft "void"		.Ft "void"
.Fn fileargs_free "fileargs_t *fa"		.Fn fileargs_free "fileargs_t *fa"
.Ft "int"		.Ft "int"
		.Fn fileargs_lstat "fileargs_t fa" "const char path" "struct stat *sb"
		.Ft "int"
.Fn fileargs_open "fileargs_t fa" "const char name"		.Fn fileargs_open "fileargs_t fa" "const char name"
.Ft "FILE *"		.Ft "FILE *"
.Fn fileargs_fopen "fileargs_t fa" "const char name" "const char *mode"		.Fn fileargs_fopen "fileargs_t fa" "const char name" "const char *mode"
.Sh DESCRIPTION		.Sh DESCRIPTION
The library is used to simplify Capsicumizing a tools that are using file system.		The library is used to simplify Capsicumizing a tools that are using file system.
Idea behind the library is that we are passing a remaining		Idea behind the library is that we are passing a remaining
.Fa argc		.Fa argc
and		and
Show All 28 Lines
.Fa mode		.Fa mode
arguments see		arguments see
.Xr open 2 .		.Xr open 2 .
The		The
.Fa rightsp		.Fa rightsp
argument contains a list of the capability rights which file should be limited to.		argument contains a list of the capability rights which file should be limited to.
For more details of the capability rights see		For more details of the capability rights see
.Xr cap_rights_init 3 .		.Xr cap_rights_init 3 .
		The
		.Fa operations
		argument limits the operations that are available using
		.Nm system.fileargs .
		pauamma_gundo.comUnsubmitted Not Done Inline Actions If the intent is emphasis, shouldn't this use .Sy instead? pauamma_gundo.com: If the intent is emphasis, shouldn't this use .Sy instead?
		.Fa operations
		is a combination of:
		.Bl -ohang -offset indent
		.It FA_OPEN
		Allow
		.Fn fileargs_open
		and
		.Fn fileargs_fopen .
		.It FA_LSTAT
		Allow
		.Fn fileargs_lstat .
		.El
.Pp		.Pp
The function		The function
.Fn fileargs_cinit		.Fn fileargs_cinit
is equivalent to		is equivalent to
.Fn fileargs_init		.Fn fileargs_init
except that the connection to the Casper needs to be provided.		except that the connection to the Casper needs to be provided.
.Pp		.Pp
The functions		The functions
Show All 13 Lines
.Fa fileargs_free		.Fa fileargs_free
close connection to the		close connection to the
.Nm system.fileargs		.Nm system.fileargs
service and free are structures.		service and free are structures.
The function handle		The function handle
.Dv NULL		.Dv NULL
argument.		argument.
.Pp		.Pp
		The function
		.Fn fileargs_lstat
		is equivalent to
		.Xr lstat 2 .
		.Pp
The functions		The functions
.Fn fileargs_open		.Fn fileargs_open
and		and
.Fn fileargs_fopen		.Fn fileargs_fopen
are respectively equivalent to		are respectively equivalent to
.Xr open 2		.Xr open 2
and		and
.Xr fopen 3		.Xr fopen 3
Show All 23 Lines
.Dv O_CREATE		.Dv O_CREATE
flag was defined the		flag was defined the
.Xr nvlist 9		.Xr nvlist 9
must contain the		must contain the
.Va mode .		.Va mode .
The		The
.Va mode		.Va mode
argument tells which what mode file should be created.		argument tells which what mode file should be created.
		.It operations (NV_TYPE_NUMBER)
		The
		.Va operations
		limits the usable operations for
		.Fa system.fileargs .
		The possible values are explained as
		.Va operations
		argument with
		.Fn fileargs_init .
.El		.El
.Pp		.Pp
The		The
.Xr nvlist 9		.Xr nvlist 9
for that functions may contain the following values and types:		for that functions may contain the following values and types:
.Bl -ohang -offset indent		.Bl -ohang -offset indent
.It cap_rights ( NV_TYPE_BINARY )		.It cap_rights ( NV_TYPE_BINARY )
The		The
Show All 20 Lines	while ((ch = getopt(argc, argv, "h")) != -1) {
}		}
}		}

argc -= optind;		argc -= optind;
argv += optind;		argv += optind;

/* Create capability to the system.fileargs service. */		/* Create capability to the system.fileargs service. */
fa = fileargs_init(argc, argv, O_RDONLY, 0,		fa = fileargs_init(argc, argv, O_RDONLY, 0,
cap_rights_init(&rights, CAP_READ));		cap_rights_init(&rights, CAP_READ), FA_OPEN);
if (fa == NULL)		if (fa == NULL)
err(1, "unable to open system.fileargs service");		err(1, "unable to open system.fileargs service");

/* Enter capability mode sandbox. */		/* Enter capability mode sandbox. */
if (cap_enter() < 0 && errno != ENOSYS)		if (cap_enter() < 0 && errno != ENOSYS)
err(1, "unable to enter capability mode");		err(1, "unable to enter capability mode");

/* Open files. */		/* Open files. */
for (i = 0; i < argc; i++) {		for (i = 0; i < argc; i++) {
fd = fileargs_open(fa, argv[i]);		fd = fileargs_open(fa, argv[i]);
if (fd < 0)		if (fd < 0)
err(1, "unable to open file %s", argv[i]);		err(1, "unable to open file %s", argv[i]);
printf("File %s opened in capability mode\n", argv[i]);		printf("File %s opened in capability mode\n", argv[i]);
close(fd);		close(fd);
}		}

fileargs_free(fa);		fileargs_free(fa);
.Ed		.Ed
.Sh SEE ALSO		.Sh SEE ALSO
.Xr cap_enter 2 ,		.Xr cap_enter 2 ,
		.Xr lstat 2 ,
.Xr open 2 ,		.Xr open 2 ,
.Xr cap_rights_init 3 ,		.Xr cap_rights_init 3 ,
.Xr err 3 ,		.Xr err 3 ,
.Xr fopen 3 ,		.Xr fopen 3 ,
.Xr getopt 3 ,		.Xr getopt 3 ,
.Xr capsicum 4 ,		.Xr capsicum 4 ,
.Xr nv 9		.Xr nv 9
.Sh BUGS		.Sh BUGS
Show All 9 Lines