mac_library(3) DG/UX B2 Security R4.12MU02 mac_library(3)
NAME
mac_library: mac_dominate, mac_equal, mac_fgetflabel, mac_freelabel,
mac_getflabel, mac_getplabel, mac_getsize, mac_glb,
mac_label_to_text, mac_lub, mac_setflabel, mac_setplabel,
mac_text_label_lnth, mac_text_to_label, mac_valid,
mac_alias_to_category, mac_alias_to_hierarchy, mac_alias_to_label,
mac_category_to_alias, mac_fsetflabel, mac_get_aliases,
mac_get_categories, mac_get_hierarchies, mac_hierarchy_to_alias,
mac_info_close, mac_info_open, mac_internal_alloc, mac_internal_copy,
mac_internal_free, mac_label_to_alias, mac_read_ject, mac_write_ject,
range_alias_to_range, range_getsize, range_internal_alloc,
range_internal_copy, range_internal_free, range_intersect,
range_lo_hi_to_range, range_read_ject, range_to_alias,
range_to_lo_hi, range_valid, range_write_ject,
dg_tuple_alias_to_tuple, dg_tuple_alloc_empty, dg_tuple_alloc_full,
dg_tuple_clear_region, dg_tuple_contains_label, dg_tuple_copy,
dg_tuple_free, dg_tuple_getsize, dg_tuple_intersect,
dg_tuple_is_empty, dg_tuple_is_subset, dg_tuple_region_exists,
dg_tuple_to_alias, dg_tuple_update_range, dg_tuple_valid - MAC
routines in libtrust.a
SYNOPSIS
The following functions are modeled after the POSIX 1003.6 Draft
ballot functions of the same name:
#include <sys/mac.h>
int mac_dominate (mac_label_t labelA,
mac_label_t labelB)
int mac_equal (mac_label_t labelA,
mac_label_t labelB)
ssize_t mac_fgetflabel (int fildes,
mac_label_t *labelp)
int mac_freelabel (mac_label_t label)
ssize_t mac_getflabel (const char *path,
mac_label_t *labelp)
ssize_t mac_getplabel (mac_label_t *labelp)
ssize_t mac_getsize (mac_label_t label)
ssize_t mac_glb (mac_label_t labelA,
mac_label_t labelB,
mac_label_t *bound)
int mac_label_to_text (mac_label_t label,
char *text,
ssize_t length)
ssize_t mac_lub (mac_label_t labelA,
mac_label_t labelB,
mac_label_t *bound)
int mac_setflabel (const char *path,
mac_label_t label)
int mac_setplabel (mac_label_t label)
int mac_text_label_lnth (mac_label_t label)
ssize_t mac_text_to_label (mac_label_t *labelp,
char *text)
int mac_valid (mac_label_t label)
The following functions are specific to the Data General
implementation and may not be portable to other systems:
#include <mac.h>
int mac_alias_to_category (int *catp,
char *alias)
int mac_alias_to_hierarchy (int *hierp,
char *alias)
ssize_t mac_alias_to_label (mac_label_t *labelp,
char *alias)
ssize_t mac_category_to_alias (int cat,
mac_alias_type type,
char **aliasp)
int mac_fsetflabel (int fildes,
mac_label_t label)
ssize_t mac_get_aliases (mac_alias_type type,
char **aliasp)
ssize_t mac_get_categories (mac_alias_type type,
char **aliasp)
ssize_t mac_get_hierarchies (mac_alias_type type,
char **aliasp)
ssize_t mac_hierarchy_to_alias (int hier,
mac_alias_type type,
char **aliasp)
int mac_info_close ();
int mac_info_open ();
int mac_internal_alloc (mac_label_t *labelp)
int mac_internal_copy (mac_label_t src,
mac_label_t dest)
int mac_internal_free (mac_label_t *labelp)
ssize_t mac_label_to_alias (mac_label_t label,
mac_alias_type type,
char **aliasp)
int mac_read_ject (ject_ject_type ject_type,
int targ_type,
const void *targ,
mac_label_t label,
textmac_pkt_t *textmac_ptr,
int flags)
int mac_write_ject (ject_ject_type ject_type,
int targ_type,
const void *targ,
mac_label_t label,
textmac_pkt_t *textmac_ptr,
int flags)
ssize_t range_alias_to_range (mac_range_t *rangep,
char *alias)
ssize_t range_getsize (mac_range_t range)
int range_internal_alloc (mac_range_t *rangep)
int range_internal_copy (mac_range_t src,
mac_range_t dest)
int range_internal_free (mac_range_t *rangep)
int range_intersect (mac_range_t range1,
mac_range_t range2,
mac_range_t *rangep)
ssize_t range_lo_hi_to_range (mac_range_t *rangep,
char *lo,
char *hi)
int range_read_ject (ject_ject_type ject_type,
int targ_type,
const void *targ,
mac_range_t range,
textrange_pkt_t *textrange_ptr,
int flags)
ssize_t range_to_alias (mac_range_t range,
mac_alias_type type,
char **aliasp)
ssize_t range_to_lo_hi (mac_range_t range,
mac_alias_type type,
char **lop,
char **hip)
int range_valid (mac_range_t range)
int range_write_ject (ject_ject_type ject_type,
int targ_type,
const void *targ,
mac_range_t range,
textrange_pkt_t *textrange_ptr,
int flags)
int dg_tuple_alias_to_tuple (mac_tuple_t *tuplep,
char *alias,
dg_sec_cred_t *sec_cred_ptr)
int dg_tuple_alloc_empty (mac_tuple_t *tuple_p)
int dg_tuple_alloc_full (mac_tuple_t *tuple_p)
int dg_tuple_clear_region (mac_tuple_t tuple_p,
int region)
int dg_tuple_contains_label (mac_tuple_t tuple,
mac_label_t label)
int dg_tuple_copy (mac_tuple_t src_tuple,
mac_tuple_t *dst_tuple)
void dg_tuple_free (mac_tuple_t *tuple_p)
ssize_t dg_tuple_getsize (mac_tuple_t tuple_p)
int dg_tuple_intersect (mac_tuple_t tuple1,
mac_tuple_t tuple2,
mac_tuple_t *result_p)
int dg_tuple_is_empty (mac_tuple_t tuple_p)
int dg_tuple_is_subset (mac_tuple_t tuple1,
mac_tuple_t tuple2)
int dg_tuple_region_exists (mac_tuple_t tuple_p,
int region)
ssize_t dg_tuple_to_alias (mac_tuple_t tuple_p,
mac_alias_type type,
char **alias,
dg_sec_cred_t *sec_cred_ptr)
int dg_tuple_update_range (mac_tuple_t tuple_p,
mac_label_t lo,
mac_label_t hi)
int dg_tuple_valid (mac_tuple_t tuple_p)
DESCRIPTION
These functions implement mandatory access control (MAC).
mac_dominate
This function determines whether labelA dominates labelB. This check
is performed by macd(1M). This function returns a 0 if labelA
dominates labelB; otherwise, it returns -1.
Errors:
EINVAL labelA or labelB is not a previously allocated label.
EINVAL labelA does not dominate labelB.
mac_equal
This function determines whether labelA is equal to labelB. This
check is performed by macd(1M). This function returns a 0 if labelA
equals labelB; otherwise, it returns -1.
Errors:
EINVAL labelA or labelB is not a previously allocated label.
EINVAL labelA does not equal labelB.
mac_fgetflabel
This function reads the MAC label of a file object. Upon success the
function allocates storage space for the MAC label (which may be
freed with a call to mac_freelabel()), places the internal
representation of the MAC label in this space, sets labelp to point
to this location, and returns its length. Upon failure the function
allocates no space, returns -1, and sets errno to the appropriate
value. To read the MAC label of a file object, a process must have
MAC attribute read access to the file object.
Errors:
ENOMEM The MAC label requires more memory than the system is able to
provide.
EBADF The file descriptor argument was out of range or did not
refer to an open file.
mac_freelabel
This function frees memory previously allocated by calls to any MAC
label function that allocates memory on the caller's behalf.
Errors:
EINVAL label is not a previously allocated label.
mac_getflabel
This function reads the MAC label of a file object. Upon success the
function allocates storage space for the MAC label (which may be
freed with a call to mac_freelabel()), places the internal
representation of the MAC label in this space, sets labelp to point
to this location, and returns its length. Upon failure the function
allocates no space, returns -1, and sets errno to the appropriate
value. To read the MAC label of a file object, a process must have
MAC attribute read access to the file object.
Errors:
ENOMEM The MAC label requires more memory than the system is
able to provide.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
mac_getplabel
This function reads the clearance label of the requesting process.
Upon success the function allocates storage space for the MAC label
(which may be freed with a call to mac_freelabel()), places the
internal representation of the MAC label in this space, sets labelp
to point to this location, and returns its length. Upon failure the
function allocates no space, returns -1, and sets errno to the
appropriate value.
Errors:
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_getsize
This function returns the size of the structure referred to by label.
Errors:
EINVAL label is not a previously allocated label.
mac_glb
This function (greatest lower bound) returns the (valid) MAC label
bound, if it exists, that is dominated by both the MAC labels labelA
and labelB and dominates all other valid MAC labels that are
dominated by both labelA and labelB.
Upon success the function allocates storage space for the MAC label
(which may be freed with a call to mac_freelabel()), places the
internal representation of the MAC label in this space, sets labelp
to point to this location, and returns its length. Upon failure the
function allocates no space, returns -1, and sets errno to the
appropriate value.
Errors:
EINVAL labelA or labelB is not a previously allocated label.
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_label_to_text
This function converts the internal representation of the MAC label
label into its text representation returned in text. The buffer
described by the text and length parameters should be large enough to
hold this representation. The buffer size required for the text
representation of a label may be obtained by calling
mac_text_label_lnth before calling this function.
Errors:
EINVAL label is not a previously allocated label or cannot be
converted to text by this process.
EINVAL the text and length parameters do not describe a sufficiently
large buffer.
mac_lub
This function (least upper bound) returns the (valid) MAC label
bound, if it exists, that dominates both the MAC labels labelA and
labelB and is dominated by all other valid MAC labels that dominate
both labelA and labelB.
Upon success the function allocates storage space for the MAC label
(which may be freed with a call to mac_freelabel()), places the
internal representation of the MAC label in this space, sets labelp
to point to this location, and returns its length. Upon failure the
function allocates no space, returns -1, and sets errno to the
appropriate value.
Errors:
EINVAL labelA or labelB is not a previously allocated label.
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_setflabel
This function sets the MAC label of a file object specified by path
to label. The caller must satisfy the requirements of the
dg_setomac(2) system call.
Errors:
EINVAL label is not a valid MAC label for path for this
process.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
EPERM An attempt was made to change the MAC label on a file
and the process does not have appropriate privilege.
EROFS An attempt was made to modify a file object on a file
system that is mounted read-only.
EBUSY The file object named by path is currently in use by
another process.
mac_setplabel
This function writes the clearance label of the requesting process.
The new clearance label is specified by label. A process must
possess appropriate privilege to perform this action.
Errors:
EINVAL label is not a previously allocated label.
EPERM The process attempted to modify its clearance label and does
not have appropriate privilege.
mac_text_label_lnth
This function returns the length of the text representation that
would be generated by mac_label_to_text() including the terminal NULL
character.
Errors:
EINVAL label is not a previously allocated label.
mac_text_to_label
This function converts the text representation of a MAC label text
into its internal representation. Upon success the function
allocates storage space for the MAC label (which may be freed with a
call to mac_freelabel()), places the internal representation of the
MAC label in this space, sets labelp to point to this location, and
returns its length. Upon failure the function allocates no space,
returns -1, and sets errno to the appropriate value.
Errors:
EINVAL label is not a previously allocated label.
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_valid
This function determines if label is a valid MAC label. This
function returns a 0 if label is valid; otherwise, it returns -1.
Errors:
EINVAL label is not a valid MAC label.
mac_alias_to_category
This function translates a category alias to its value as defined in
the MAC alias database. catp is set to this value. The category
must be defined and the subject clearance label must contain the
specified category or the subject must have appropriate privilege in
order for this function to succeed.
Errors:
EINVAL alias is not a valid category alias for this process.
mac_alias_to_hierarchy
This function translates a hierarchy alias to its value as defined in
the MAC alias database. hierp is set to this value. The hierarchy
must be defined and the hierarchy in the subject clearance label must
be equal to or greater then the specified hierarchy or the subject
must have appropriate privilege in order for this function to
succeed.
Errors:
EINVAL alias is not a valid hierarchy alias for this process.
mac_alias_to_label
This function converts the text representation of a MAC label alias
into its internal representation. Upon success the function
allocates storage space for the MAC label (which may be freed with a
call to mac_freelabel()), places the internal representation of the
MAC label in this space, sets labelp to point to this location, and
returns its length. Upon failure the function allocates no space,
returns -1, and sets errno to the appropriate value.
Errors:
EINVAL label is not a previously allocated label.
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_category_to_alias
This function translates a category value to its alias as defined in
the mac alias database. The function returns the long form of the
alias by default. The category must be defined and the subject
clearance label must contain the specified category or the subject
must have appropriate privilege in order for this function to
succeed. The function allocates the string *aliasp and returns its
length upon success; it returns -1 and the appropriate errno on
failure.
type can have the following flags set:
M_ABBREV Return the abbreviation, not the default long name.
Errors:
EINVAL cat is not a valid category for this process.
mac_fsetflabel
This sets the MAC label on the file object specified by fildes to the
MAC label label. The function is similar to the POSIX
mac_setflabel(), but it requires a file descriptor instead of a
pathname.
Errors:
EINVAL label is not a valid MAC label for path for this process.
EPERM An attempt was made to change the MAC label on a file and the
process does not have appropriate privilege.
EROFS An attempt was made to modify a file object on a file system
that is mounted read-only.
EBUSY The file object named by path is currently in use by another
process.
EBADF The file descriptor argument was out of range or did not
refer to an open file.
mac_get_aliases
This function lists all MAC label aliases currently defined in the
system for appropriately privileged subjects. Upon success, the
function allocates the string *aliasp and returns its length; on
failure, it returns -1 and the appropriate errno. The aliases are
listed (when possible) in order of ascending dominance.
type must have either M_ALIAS or M_DEFINITION set. M_ABBREV and
M_ALL are optional. Valid type flags are as follows:
M_ALIAS List the MAC label aliases if any exist. If none
exist, list the MAC label in terms of hierarchy and
categories. M_ALIAS and M_DEFINITION are mutually
exclusive.
M_DEFINITION List the MAC labels in terms of hierarchy and
categories instead of alias names. M_DEFINITION and
M_ALIAS are mutually exclusive.
M_ABBREV List abbreviations, not the default long names.
M_ABBREV can be OR'ed with any of the other MAC alias
type values.
M_ALL List all equivalent aliases on a separate line with
each alias separated by a single space character. The
last substring is the alias in terms of hierarchy and
categories. The newline character ('\n') is the last
character in the line. The last defined alias is
listed first. M_ALL can be OR'ed with any of the other
MAC alias type values.
Errors:
EPERM The subject is not appropriately privileged.
EINVAL type is not a valid choice as defined above.
ENOMEM There was insufficient memory to allocate *aliasp.
mac_get_categories
This function lists all MAC label category aliases currently defined
in the system for appropriately privileged subjects. Upon success,
the function allocates the string *aliasp and returns its length; on
failure, it returns -1 and the appropriate errno. The aliases are
listed in order of ascending defined value.
type must be M_CAT. M_ABBREV is optional. type values are:
M_CAT List the MAC label category aliases if any exist.
M_ABBREV List the abbreviations, not the default long names.
M_ABBREV can be OR'ed with M_CAT.
Errors:
EPERM The subject is not appropriately privileged.
EINVAL type is not a valid choice as defined above.
ENOMEM There was insufficient memory to allocate *aliasp.
mac_get_hierarchies
This function lists all MAC label hierarchy aliases currently defined
in the system for appropriately privileged subjects. Upon success,
the function allocates the string *aliasp and returns its length; on
failure, it returns -1 and the appropriate errno. The aliases are
listed in order of ascending dominance.
type must be M_HIER. M_ABBREV is optional. type values are:
M_HIER List the MAC label hierarchy aliases if any exist.
M_ABBREV List the abbreviations, not the default long names.
M_ABBREV can be OR'ed with M_HIER.
Errors:
EPERM The subject is not appropriately privileged.
EINVAL type is not a valid choice as defined above.
ENOMEM There was insufficient memory to allocate *aliasp.
mac_hierarchy_to_alias
This function translates a hierarchy value to its alias as defined in
the mac alias database. The function returns the long form of the
alias by default. The hierarchy must be defined and hierarchy in the
subject clearance label must be equal to or greater than the
specified hierarchy or the subject must have appropriate privilege in
order for this function to succeed. The function allocates the
string *aliasp and returns its length upon success; it returns -1 and
the appropriate errno on failure.
type can have the following flags set:
M_ABBREV Return the abbreviation, not the default long name.
Errors:
EINVAL hier is not a valid category for this process.
mac_info_close
This function closes the connection to macd(1M). It is not necessary
to call this function unless you desire special processing outside
the features provided by the MAC library routines.
Errors:
None (other than ENOSYS).
mac_info_open
This function opens a connection to macd(1M). This call is not
necessary unless you need features not provided by the MAC library
routines. All functions that need to communicate with macd will
automatically open the connection.
If this function is not called, then every function call that uses
macd opens the connection and closes it when done. The connection to
macd should be held open only as long as is necessary and should be
closed as soon as possible with mac_info_close().
Errors:
None (other than ENOSYS).
mac_internal_alloc
This function allocates storage for a MAC label. The function
allocates a MAC label for mac_read_ject() and mac_write_ject(). The
function also initializes the MAC label structure to currently valid
values specifying that it is not a MAC label. If successful, the
function returns 0; otherwise, the function returns -1 with the
appropriate errno.
Errors:
ENOMEM The MAC label requires more memory than the system is able to
provide.
mac_internal_copy
This function is used to copy the MAC label src to the MAC label
dest.
Errors:
EINVAL src or dest is not a valid MAC label as allocated by
mac_internal_alloc().
mac_internal_free
This function frees the specified MAC label storage pointed to by
labelp.
Errors
EINVAL labelp is not a label allocated by mac_internal_alloc() or
labelp is NULL.
mac_label_to_alias
This function translates the specified MAC label to its alias as
defined in the MAC alias database. The label or its component
hierarchy and categories must be defined and the subject clearance
label must dominate the specified label or the subject must have
appropriate privilege in order for this function to succeed. The
function allocates the string *aliasp and returns its length upon
success; it returns -1 and the appropriate errno on failure.
type must have either M_ALIAS or M_DEFINITION set. M_ABBREV and
M_ALL are optional:
M_ALIAS Return the MAC label alias if one exists. If one does
not exist, return the MAC label in terms of hierarchy
and categories. M_ALIAS and M_DEFINITION are mutually
exclusive.
M_DEFINITION Return the MAC label in terms of hierarchy and
categories instead of a single alias name.
M_DEFINITION and M_ALIAS are mutually exclusive.
M_ABBREV Return the abbreviation, not the default long name.
M_ABBREV can be OR'ed with any of the other MAC alias
type values.
M_ALL Return all the aliases defined for this label. The
default is to return the last defined alias. M_ALL can
be OR'ed with any of the other MAC alias type values.
Errors:
EINVAL label is not a previously allocated label.
EINVAL type is not a valid choice as defined above.
mac_read_ject
This function reads the MAC label of the specified target. The
process must have attribute read access to the target.
ject_type must be JECT_OBJECT or JECT_SUBJECT.
targ_type If ject_type is JECT_OBJECT, valid values are T_FILE,
T_SYMLINK and T_FD. If ject_type is JECT_SUBJECT, then
the only valid value is T_PROC.
targ ject_type targ_type Value
JECT_OBJECT T_FILE pathname (char *)
JECT_OBJECT T_SYMLINK pathname (char *)
JECT_OBJECT T_FD pointer to file descriptor (int *)
JECT_SUBJECT T_PROC pointer to process ID (pid_t *)
label MAC label previously allocated by mac_internal_alloc()
textmac_ptr Currently unused - must be set to NULL.
flags Must be 0. There are currently no values defined for
flags.
Errors:
EINVAL A parameter is not as defined above
EINVAL label is not a previously allocated label.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
mac_write_ject
This function sets the specified MAC label on the specified target.
A process must possess appropriate privilege to perform this action.
ject_type Must be JECT_OBJECT or JECT_SUBJECT.
targ_type If ject_type is JECT_OBJECT, valid values are T_FILE,
T_SYMLINK or T_FD. If ject_type is JECT_SUBJECT, then
the only valid value is T_PROC.
targ ject_type targ_type Value
JECT_OBJECT T_FILE pathname (char *)
JECT_OBJECT T_SYMLINK pathname (char *)
JECT_OBJECT T_FD pointer to file descriptor (int *)
JECT_SUBJECT T_PROC pointer to process ID (pid_t *)
label MAC label previously allocated by mac_internal_alloc()
textmac_ptr Currently unused - must be set to NULL.
flags Must be one of the following values:
MWJ_SETOMAC Set the MAC label implicit labels
can be affected
MWJ_SETOMAC_ONLY Set the explicit MAC label only
MWJ_SETTMPOMAC Set a temporary MAC label
MWJ_CVT_TO_IMPLICIT Convert the target's explicit MAC
label to an implicit if possible
Errors:
EINVAL label is not a valid MAC label for path for this
process.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
EPERM An attempt was made to change the MAC label on a file
and the process does not have appropriate privilege.
EROFS An attempt was made to modify a file object on a file
system that is mounted read-only.
EBUSY The file object named by path is currently in use by
another process.
range_alias_to_range
This function converts the text representation of a MAC range text
into its internal representation. Upon success the function
allocates storage space for the MAC range (which may be freed with a
call to range_internal_free()), places the internal representation of
the range in this space, sets rangep to point to this location, and
returns its length. Upon failure the function allocates no space,
returns -1, and sets errno to the appropriate value.
Errors:
EINVAL range is not a previously allocated label.
ENOMEM The MAC range requires more memory than the system is able to
provide.
range_getsize
This function returns the size in bytes of the MAC range structure
pointed to by range.
Errors:
EINVAL range is not a previously allocated range.
range_internal_alloc
This function allocates storage for a MAC range. This function is
used to allocate a MAC range for range_read_ject() and
range_write_ject(). The function also initializes the MAC range
structure to currently valid values specifying that it is not a MAC
range. If successful, the function returns 0; otherwise, the
function returns -1 with the appropriate errno.
Errors:
ENOMEM The MAC label requires more memory than the system is able to
provide.
range_internal_copy
This function is used to copy the MAC range src to the MAC range
dest.
Errors:
EINVAL src or dest is not a valid MAC range as allocated by
range_internal_alloc().
range_internal_free
This function is used to free the specified MAC range storage pointed
to by rangep.
Errors:
EINVAL rangep is not a MAC range previously allocated by
range_internal_alloc().
EINVAL rangep is NULL.
range_intersect
This function takes two MAC ranges and generates their intersection.
Upon success, the function allocates storage space for the MAC
range (which may be freed with a call to range_internal_free()), sets
rangep to point to this location, and returns 0. Upon failure, the
function allocates no space, returns -1, and sets errno to the
appropriate value.
Errors:
EINVAL rangep is not a pointer to a NULL.
EINVAL range1 or range2 is NULL.
EINVAL range1 and range2 have different versions or types.
EINVAL range1 and range2 are completely disjoint, and have no
intersection.
ENOMEM The MAC range requires more memory than the system is able to
provide.
range_lo_hi_to_range
This function converts the text representation of a MAC range in
terms of its low MAC label alias lo and its high MAC label alias hi
into its internal representation. Upon success the function
allocates storage space for the MAC range (which may be freed with a
call to range_internal_free()), places the internal representation of
the range in this space, sets rangep to point to this location, and
returns its length. Upon failure the function allocates no space,
returns -1, and sets errno to the appropriate value.
Errors:
EINVAL range is not a previously allocated label.
ENOMEM The MAC range requires more memory than the system is able to
provide.
range_read_ject
This function reads the MAC range of the specified target. The
process must have attribute read access to the target.
ject_type must be JECT_OBJECT or JECT_SUBJECT.
targ_type If ject_type is JECT_OBJECT, valid values are T_FILE,
T_SYMLINK and T_FD. If ject_type is JECT_SUBJECT, then
the only valid value is T_PROC.
targ ject_type targ_type Value
JECT_OBJECT T_FILE pathname (char *)
JECT_OBJECT T_SYMLINK pathname (char *)
JECT_OBJECT T_FD pointer to file descriptor (int *)
JECT_SUBJECT T_PROC pointer to process ID (pid_t *)
range MAC range previously allocated by
range_internal_alloc().
textrange_ptr Currently unused - must be set to NULL.
flags Must be 0. There are currently no values defined for
flags.
Errors:
EINVAL A parameter is not as defined above
EINVAL range is not a previously allocated range.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
range_to_alias
This function translates the specified MAC range to its alias. The
MAC range alias has the format RANGE_ALIAS_FMT as defined in mac.h
and is composed of the low MAC label alias and the high MAC label
alias. The range or its component hierarchies and categories must be
defined and the subject clearance label must dominate both the low
and high label of the specified range or the subject must have
appropriate privilege in order for this function to succeed. The
function allocates storage for lop and hip, the low and high label
aliases.
The function returns:
0 if the subject MAC label dominates both ends of the specified
MAC range. *aliasp is of the form:
-L low-end-MAC-alias -H high-end-MAC-alias
1 if the subject MAC label dominates the low end of the
specified MAC range, but not the high end. *aliasp is of the
form:
-L low-end-MAC-alias -H ?
-1 if the subject MAC label dominates neither end of the
specified MAC range. In this case *aliasp is not allocated
any memory.
type must have either M_ALIAS or M_DEFINITION set. M_ABBREV and
M_ALL are optional:
M_ALIAS Return the MAC range alias as two MAC label aliases if they
exist. If they do not exist, return the MAC labels in
terms of hierarchy and categories. M_ALIAS and
M_DEFINITION are mutually exclusive. M_DEFINITION Return
the low and high MAC label in terms of hierarchy and
categories instead of the alias name. M_DEFINITION and
M_ALIAS are mutually exclusive.
M_ABBREV Return the abbreviation, not the default long name.
M_ABBREV can be OR'ed with any of the other MAC alias type
values.
M_ALL Return all the aliases defined for the low and high MAC
label. The default is to return the last defined alias.
M_ALL can be OR'ed with any of the other MAC alias type
values.
*aliasp must be initialized to NULL.
Errors:
EINVAL range is not a previously allocated range.
EINVAL type is not a valid choice as defined above.
range_to_lo_hi
This function translates the specified MAC range to its low and high
label aliases as defined in the MAC alias database. The range or its
component hierarchies and categories must be defined and the subject
clearance label must dominate both the low and high label of the
specified range or the subject must have appropriate privilege in
order for this function to succeed. The function allocates storage
for lop and hip, the low and high label aliases.
The function returns:
0 if the subject MAC label dominates both ends of the specified
MAC range. In this case *lop contains the MAC range low end
alias and *hip contains the MAC range high end alias.
1 if the subject MAC label dominates the low end of the
specified MAC range, but not the high end. In this case *lop
contains the MAC range low end alias and *hip is not allocated
any memory.
-1 if the subject MAC label dominates neither end of the
specified MAC range. In this case *lop and *hip are not
allocated any memory.
type must have either M_ALIAS or M_DEFINITION set. M_ABBREV and
M_ALL are optional. Valid types are:
M_ALIAS Return the MAC label alias if one exists. If one
does not exist, return the MAC label in terms of
hierarchy and categories. M_ALIAS and M_DEFINITION
are mutually exclusive. M_DEFINITION Return the MAC
label in terms of hierarchy and categories instead of
a single alias name. M_DEFINITION and M_ALIAS are
mutually exclusive.
M_ABBREV Return the abbreviation, not the default long name.
M_ABBREV can be OR'ed with any of the other MAC alias
type values.
M_ALL Return all the aliases defined for this label. The
default is to return the last defined alias. M_ALL
can be OR'ed with any of the other MAC alias type
values.
*lop and *hip must be initialized to NULL.
Errors:
EINVAL range is not a previously allocated range.
EINVAL type is not a valid choice as defined above.
range_valid
This function determines if range is a valid MAC label. This
function returns a 0 if range is valid; otherwise, it returns -1.
Errors:
EINVAL range is not a valid MAC range.
range_write_ject
This function sets the specified MAC range on the specified target.
A process must possess appropriate privilege to perform this action.
ject_type Must be JECT_OBJECT or JECT_SUBJECT.
targ_type If ject_type is JECT_OBJECT, valid values are T_FILE,
T_SYMLINK or T_FD. If ject_type is JECT_SUBJECT, then
the only valid value is T_PROC.
targ ject_type targ_type Value
JECT_OBJECT T_FILE pathname (char *)
JECT_OBJECT T_SYMLINK pathname (char *)
JECT_OBJECT T_FD pointer to file descriptor (int *)
JECT_SUBJECT T_PROC pointer to process ID (pid_t *)
range MAC label previously allocated by
range_internal_alloc()
textrange_ptr Currently unused - must be set to NULL.
flags Must be 0.
Errors:
EINVAL range is not a valid MAC range for path for this
process.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOENT The named file object does not exist or path points to
an empty string.
EPERM An attempt was made to change the MAC range on a file
and the process does not have appropriate privilege.
EROFS An attempt was made to modify a file object on a file
system that is mounted read-only.
EBUSY The file object named by path is currently in use by
another process.
dg_tuple_alias_to_tuple
This function converts the text representation of a MAC tuple alias
into its internal representation. Upon success the function
allocates storage space for the MAC tuple (which may be freed with a
call to dg_tuple_free()), places the internal representation of the
MAC tuple in this space, sets tuple_p to point to this location, and
returns its length. The calling process must have access to
translate the specified alias and, if the sec_cred_ptr argument is
not NULL, a process with the specified credentials must also have
access to translate the specified alias, or the call will fail. Upon
success the function returns 0. Upon failure, the function allocates
no space, returns -1, and sets errno to the appropriate value.
Errors:
EINVAL alias is not a a valid MAC tuple alias.
EACCES The calling process, and/or a process with the specified
credentials if sec_cred_ptr is not NULL, does not have access
to translate alias.
ENOMEM The MAC tuple requires more memory than the system is able to
provide.
dg_tuple_alloc_empty
This function allocates storage for a MAC tuple which is initially
empty. That is to say, the tuple contains no MAC ranges in any
region (the type of each range is set to MAC_RANGE_TYPE_NO_RANGE).
If successful, the function returns 0; otherwise, the function
returns -1 with the appropriate errno.
Errors:
ENOMEM The MAC tuple requires more memory than the system is able to
provide.
dg_tuple_alloc_full
This function allocates storage for a MAC tuple which is initially
full. That is to say, the tuple contains all MAC ranges
(administrative region, user region and virus prevention region)
which cover their entire regions, respectively. If successful, the
function returns 0, otherwise, the function returns -1 with the
appropriate errno.
Errors:
ENOMEM The MAC tuple requires more memory than the system is able to
provide.
dg_tuple_clear_region
This function removes the MAC range from region in the specified
tuple. It does this by setting the type for the range in region to
MAC_RANGE_TYPE_NO_RANGE. region can have one of the following
values:
ADMIN_MAC_REGION Administrative MAC region.
USER_MAC_REGION User MAC region.
VP_MAC_REGION Virus prevention MAC region.
If successful, the function returns 0, otherwise, the function
returns -1 with the appropriate errno.
Errors:
EINVAL The specified tuple, tuple_p is not valid or region is not a
valid region.
dg_tuple_contains_label
This function determines whether or not label is contained within
tuple. A MAC tuple contains a label if the label is within any of
the tuple's MAC ranges. If the tuple contains the label, the
function returns 1; otherwise, the function returns 0.
dg_tuple_copy
This function allocates space for dst_tuple and copies src_tuple into
the newly allocated space. If successful, the function returns 0
otherwise, the function returns -1 with the appropriate errno.
Errors:
ENOMEM The MAC tuple requires more memory than the system is able to
provide.
dg_tuple_free
This function frees memory previously allocated for a MAC tuple.
dg_tuple_getsize
This function returns the size of the structure referred to by
tuple_p.
dg_tuple_intersect
This function takes two MAC tuples and generates their intersection.
Upon success, the function allocates storage space for the MAC tuple,
sets result_p to point to this location, and returns 0. Upon
failure, the function allocates no space, returns -1, and sets errno
to the appropriate value. The intersection of two MAC tuples is
calculated as follows. For each region in the tuples, if both tuples
contain a range in the region, then the corresponding range in the
result tuple is the intersection of the two ranges. If either tuple
does not contain a range in the region, the corresponding region in
the result tuple does not contain a range.
Errors:
EINVAL tuple1 or tuple2 is NULL.
ENOMEM The MAC tuple requires more memory than the system is able to
provide.
dg_tuple_is_empty
This function determines whether the MAC tuple referenced by tuple_p
is empty. A MAC tuple is empty if it contains no MAC ranges in any
region. If tuple is empty, the function returns 0, otherwise, it
returns -1.
dg_tuple_is_subset
This function determines whether or not tuple1 is a subset of tuple2.
tuple1 is a subset of tuple2 if each MAC range in tuple1 is a subset
of the corresponding MAC range in tuple2. If tuple1 is a subset of
tuple2, this function returns 1; otherwise, it returns 0.
dg_tuple_region_exists
This function determines whether or not a MAC range exists in region
of the MAC tuple referenced by tuple_p. region can have one of the
following values:
ADMIN_MAC_REGION Administrative MAC region.
USER_MAC_REGION User MAC region.
VP_MAC_REGION Virus prevention MAC region.
If a range exists, this function returns 1; otherwise, it returns 0.
The function will also return 0 on error and will set errno to one of
the following values:
Errors:
EINVAL tuple_p does not reference a valid MAC tuple.
dg_tuple_to_alias
This function translates the specified MAC tuple to its alias as
defined in the MAC alias database. A MAC tuple alias is comprised of
the MAC range aliases for each MAC range in the tuple. For example,
an alias for a MAC tuple which has a full admin and user MAC range
would be "-L ADMIN_LO -H ADMIN_HI -L USER_LO -H USER_HI." All labels
or their component hierarchies and categories must be defined. The
calling process must have access to translate the specified tuple
and, if the sec_cred_ptr argument is not NULL, a process with the
specified credentials must also have access to translate the
specified tuple, or the call will fail. The function allocates the
string *aliasp and returns its length upon success; it returns -1 and
the appropriate errno on failure.
type must have either M_ALIAS or M_DEFINITION set. M_ABBREV and
M_ALL are optional:
M_ALIAS Return the aliases for the MAC labels if they exist.
If one does not exist, return that MAC label in terms
of hierarchy and categories. M_ALIAS and M_DEFINITION
are mutually exclusive.
M_DEFINITION Return the MAC labels in terms of hierarchy and
categories instead of single alias names. M_DEFINITION
and M_ALIAS are mutually exclusive.
M_ABBREV Return the abbreviation, not the default long name for
MAC label aliases. M_ABBREV can be OR'ed with any of
the other MAC alias type values.
M_ALL Return all the aliases defined for the labels. The
default is to return the last defined alias. M_ALL can
be OR'ed with any of the other MAC alias type values.
Errors:
EINVAL tuple_p does not reference a valid MAC tuple.
EINVAL type is not a valid choice as defined above.
EACCES The calling process, or a process with the specified
credentials if sec_cred_ptr is not NULL, does not have access
to translate tuple_p.
ENOMEM There was not enough memory to perform the operation.
dg_tuple_update_range
This function updates a MAC range in the MAC tuple referenced by
tuple_p. The lo and hi MAC labels must be in the same MAC region and
hi must dominate lo. If tuple_p did not previously have a range in
the region that contains lo and hi, the new range is added. If a
range already exists in the region, it is replaced by lo and hi.
Upon success, the function returns 0. Upon failure, the function
returns -1 and sets errno to the appropriate value.
Errors:
EINVAL tuple_p does not reference a valid MAC tuple.
EINVAL lo or hi is not a valid MAC label.
EINVAL lo and hi are not in the same MAC region.
EINVAL hi does not dominate lo.
dg_tuple_valid
This function determines if tuple_p references a valid MAC tuple.
This function returns 0 if tuple_p is valid; otherwise, it returns
-1.
Errors:
EINVAL tuple_p does not reference a valid MAC tuple.
SEE ALSO
macd(1M), dg_mac_access(2), dg_setomac(2), dg_settuple(2),
settuple(1M), aa_library(3), acl_library(3), audit_library(3),
cap_library(3), mac_defs(4M).
Licensed material--property of copyright holder(s)