GETFLAB(2)

NAME
getflab, fgetflab, setflab, fsetflab - get or set file security label and privilege

SYNOPSIS
#include <sys/label.h>

getflab(name, labp)
char *name;
struct label *labp;

fgetflab(fildes, labp)
struct label *labp;

setflab(name, labp)
char *name;
struct label *labp;

fsetflab(fildes, labp)
struct label *labp;

DESCRIPTION
Getflab copies the security label from the the named file into the structure pointed to by labp. Fgetlab copies the security label from an open file specified by file descriptor. The field lb_junk is always zero.

The structure of a security label as defined in <sys/label.h> is

    #define	LABSIZ	60
    struct	labpriv {
    	unsigned int	lp_junk : 16,	/* poison level, see syslog(2) */
    		lp_flag : 2,
    		lp_fix : 2,	/* fixity */
    		lp_t : 6,	/* capabilities */
    		lp_u : 6;	/* licenses */
    };
    struct	label {
    	struct labpriv	lb_priv;
    	unsigned char	lb_bits[LABSIZ];
    #	define lb_junk	lb_priv.lp_junk
    #	define lb_flag	lb_priv.lp_flag
    #	define lb_t	lb_priv.lp_t
    #	define lb_u	lb_priv.lp_u
    #	define lb_fix	lb_priv.lp_fix
    };
    		/* codes in lb_flag */
    #define L_YES	1
    #define	L_NO	2
    #define	L_BITS	3
    		/* codes in lb_fix */
    #define	F_LOOSE	0
    #define	F_FROZEN	1
    #define	F_RIGID	2
    #define	F_CONST	3
    		/* bits of lb_t and lb_u */
    #define	T_SETPRIV	001	/* may set file privilege */
    #define	T_SETLIC	002	/* may change process license */
    #define	T_NOCHK	004	/* exempt from label checking */
    #define	T_EXTERN	010	/* may introduce foreign data */
    #define	T_UAREA	020	/* may write in u area */
    #define	T_LOG	040	/* may execute syslog() call */

Three types of labels are distinguished by the lb_flag field:

L_YES
    The file can be read or modified without regard to label. Its inode data (see stat(2)) have permanent conventional values. Null(4), log(4), and fd(4) are labeled L_YES.

L_NO
    The the file and its inode cannot be read or written except by processes with capability T_NOCHK. A L_NO label may be changed by processes with capability T_EXTERN, unless prevented by F_CONST described below.

L_BITS
    The label has a `lattice value', given by lb_bits and so called because the values form a mathematical lattice with bitwise AND as the meet operation and OR as the join.

Each process and each file has a label. Normally data may only flow `up' the lattice. The destination of a read, write, inode query, or inode change must have a lattice value that dominates (bitwise) the lattice value of the source, unless the process concerned has capability T_NOCHK.

To assure upward flow, a read(2) or an inode query (e.g. stat(2)) normally causes the file label to be OR-ed into the process label. Similarly a write(2) or an inode change (as by chmod(2) or link(2)) causes the process label to be OR-ed into the file label. However such side-effect changes in a file or process label may happen only if the label is loose (see below) and the new label is dominated by the process ceiling; see getplab(2). Otherwise the system call terminates with error ELAB.

Security checks are independent of, and made prior to, the permission checks described in access(2). Super-user processes are subject to security checks.

Setflab replaces the security label of the named file with the contents of the structure pointed to by labp. Fsetflab replaces the security label of an open file specified by file descriptor. If the new label has flag L_BITS, the new lattice value must dominate the old one, dominate the process label, and be dominated by the process ceiling. If the new label has flag L_NO, the old label must be dominated by the process ceiling. Flag L_YES is an error. The field lb_junk is ignored.

The field lb_t contains `capability' bits; lb_u contains corresponding `license' bits; their meanings are described in getplab(2) and exec(2). The two fields together are known as `privileges'. Any file that has nonzero privileges is called `trusted' and cannot be changed, in contents or in inode, except by processes with capability T_SETPRIV.

Aside from considerations of trustedness, a label can be changed with more or less freedom according to its `fixity', lb_fix:

F_LOOSE
    Any process can change the lattice value of a loose file label implicitly as a side effect as described above or (up to the process ceiling) explicitly with setflab or fsetflab. The file owner or the super-user can change the fixity.

F_FROZEN
    The lattice value of a frozen label cannot change. The fixity can be changed by the file owner or the super-user.

F_RIGID
    Only processes with capability T_EXTERN can change a rigid label; see getplab(2). The labels of external media, such as terminals, tapes or disks, are automatically rigid. A loose or frozen label on a stream (see stream(4)) can be changed to rigid. This facility allows filters, such as mux(9.1), to make pipes behave like external devices. The fixity of a rigid label cannot change.

F_CONST
    A constant label may not be changed. The labels of certain special files, such as and are automatically constant; no other labels may become constant.

SEE ALSO
getplab(2), getlab(1), labLE(3), setlab(8), unsafe(2), signal(2)

DIAGNOSTICS
EFAULT, EIO, ELAB, ELOOP, ENOENT, ENOTDIR