getesfient(3)getesfient(3)NAME
getesfient, getesfinam, setprfient, endprfient, putesfinam, getprfient,
getprfinam, putprfinam, copyesfient - Manipulate file control database
entry (Enhanced Security)
SYNOPSIS
#include <sys/types.h> #include <sys/security.h> #include <prot.h>
struct es_file *getesfient(
void ); struct es_file *getesfinam(
char *name ); void setprfient(
void ); void endprfient(
void ); int putesfinam(
char *name,
struct es_file *pr ); struct es_file *copyesfient(
struct es_file *pr );
Note
NOTE: The getprfient(), getprfinam(), and putprfinam() routines have
been replaced by getesfient(), getesfinam(), and putesfinam() respec‐
tively.
LIBRARY
Security Library (libsecurity.so)
NOTE: In order to quickstart a program, the program must be linked as
follows: -lsecurity -ldb -laud -lm
See the shared library discussion in the Programmer's Guide for more
information about using the quickstarting feature.
PARAMETERS
Specifies a file control database entry name. Specifies a file con‐
trol database entry structure.
DESCRIPTION
The getesfient(), getesfinam(), and copyesfient() functions each return
a pointer to an object with the following structure containing the sep‐
arated-out fields of a line in the file control database. Each line in
the database contains a es_file structure, declared in the prot.h
header file as follows:
/* File Control Database Entry */
struct esfi_field {
char *fd_name; /* Holds full path name */
uid_t fd_uid; /* uid of owner */
gid_t fd_gid; /* gid of group */
mode_t fd_mode; /* permissions */
char *fd_type; /* file type (one of r,b,c,d,f,s,m) */
mand_ir_t *fd_slevel; /* sensitivity level for file */
acle_t *fd_acl; /* access control list for file */
int fd_acllen; /* number of entries in fd_acl */
priv_t *fd_pprivs; /* potential privileges */
priv_t *fd_gprivs; /* granted privileges */ };
struct esfi_flag {
unsigned int
fg_name:1, /* Is fd_name set? */
fg_uid:1, /* Is fd_uid set? */
fg_gid:1, /* Is fd_gid set? */
fg_mode:1, /* Is fd_mode set? */
fg_type:1, /* Is fd_type set? */
fg_slevel:1, /* Is fd_slevel set? */
fg_acl:1, /* Is fd_acl set? */
fg_pprivs:1, /* Is fd_pprivs set? */
fg_gprivs:1 /* Is fd_gprivs set? */
; };
struct es_file {
AUTH_ESCAP_COMMON
size_t fieldlen;
struct esfi_field *ufld;
struct esfi_flag *uflg; };
The getesfient() function when first called returns a pointer to the
first es_file structure in the database; thereafter, it returns a
pointer to the next es_file structure in the database, so successive
calls can be used to search the database. The getesfinam() function
searches from the beginning of the database until a file name matching
name is found, and returns a pointer to the particular structure in
which it was found. If an end-of-file or an error is encountered on
reading, these functions return a null pointer.
The copyesfient() function copies pr, and the fields to which it
refers, to a newly allocated data area. Because the getesfient() and
putesfient() functions reuse a static structure when accessing the
database, the values of any entry must be saved if the database rou‐
tines are used again. The es_file structure returned by copyesfient()
can be freed using the free() function.
A call to the setprfient() function has the effect of rewinding the
file control database to allow repeated searches. The endprfient()
function can be called to close the file control database when process‐
ing is complete.
The putesfinam() function puts a new or replaced file control entry pr
with key name into the database. If the uflg->fg_name field is a 0
(zero), the requested entry is deleted from the file control database.
The putesfinam() function locks the database for all update operations,
and performs a endprfient() after the update or failed attempt.
The file control database stores a list of entries for security rele‐
vant files. This database is used by the setfiles program to assign and
maintain the security attributes of system files.
The fd_name pointer refers to the file name, which can be an absolute
pathname or a pathname whose last component is an * (asterisk), which
is treated as a wildcard entry. Entries that refer to a specific file
in a directory supersede the wildcard entry if the absolute pathname
precedes the wildcard entry in the database. The fd_uid and fd_gid
fields are the numeric owner and group of the file. The fd_mode field
is the mode word, including owner, group, and other permissions, as
well as the SUID and SGID bits. The fd_type field contains a one-char‐
acter file type indicator: r (regular), b (block-special), c (charac‐
ter-special), d (directory), f (FIFO), s (symbolic link). The fd_acl
field, if set, references the textual representation of the file's
access control list. The fd_acllen field is not currently used.
NOTES
Programs using these functions must be compiled with -lsecurity.
Structures returned by the database routines contain pointers to char‐
acter strings and lists rather than being self-contained. The copy
function must be used rather than doing a structure assignment to save
a returned structure.
The value returned by getesfinam() and getesfient() refers to a struc‐
ture that is overwritten by calls to these functions. To retrieve an
entry, modify it, and replace it in the database, you must copy the
entry using copyesfient() and supply the modified buffer to putesfi‐
nam().
CAUTIONS
Structures returned by the database routines contain pointers to char‐
acter strings and lists rather than being self-contained. The copy‐
esfient() function must be used rather than doing a structure assign‐
ment to save a returned structure.
The value returned by the getesfient() and getesfinam() functions
refers to a structure that is overwritten by calls to the function. To
retrieve an entry, modify it, and replace it in the database, you must
copy the entry using the copyesfient() function and supply the modified
buffer to the putesfient() function.
RETURN VALUES
The getesfient() and getesfinam() functions return null pointers on EOF
or an error.
The putesfinam() function returns a value of 0 (zero) if it cannot add
or update the entry.
The copyesfient() function returns a pointer, or NULL on (allocation)
error.
FILES
Description file of directories, devices, control, and commands modi‐
fied for security. General security databases file.
SEE ALSO
Files: authcap(4), files(4)
Security
getesfient(3)