dg_getomac(2)            DG/UX B2 Security R4.12MU02           dg_getomac(2)


NAME
       dg_getomac - get the mandatory access control (MAC) label of an
       object

SYNOPSIS
       #include <sys/types.h>
       #include <sys/dg_tparms.h>
       #include <sys/mac.h>

       int dg_getomac(targ_type, targ, label, labsize, textmac, textmacsize)
       int    targ_type;
       const void    *targ;
       mac_label_struct_t   *label;
       int    *labsize;
       char   *textmac;
       int    *textmacsize;

   where:
       targ_type   A token that identifies the type of object whose MAC
                   label is fetched.  The available tokens are defined in
                   sys/dg_tparms.h as follows:
                     T_PROC  The object is an existing process on the
                             system.
                     T_FILE  The object is a file identified by a pathname.
                     T_FD    The object is a file, socket or pipe identified
                             by a descriptor.
                     T_SYMLINK
                             The object is a symbolic link identified by a
                             pathname.
                     T_MSG   The object is a message queue identified by a
                             message queue identifier.
                     T_SHM   The object is a shared memory segment
                             identified by a shared memory segment
                             identifier.
                     T_SEM   The object is a semaphore identified by a
                             semaphore set identifier.

       targ        The address of the identifier of the object whose MAC
                   label is fetched.  The value of targ_type determines the
                   type of entity that targ points to as follows:
                     T_PROC  targ points to a process id (type pid_t).
                     T_FILE  targ points to a pathname string.
                     T_FD    targ points to a file, socket or pipe
                             descriptor.
                     T_SYMLINK
                             targ points to a pathname string.
                     T_MSG   targ points to a message queue identifier.
                     T_SHM   targ points to shared memory segment
                             identifier.
                     T_SEM   targ points to a semaphore set identifier.

       label       The address of a mac_label_struct_t structure into which
                   dg_getomac copies the object's MAC label.

       labsize     A pointer to the size in bytes of the binary MAC label
                   structure.

       textmac     A pointer to a buffer to receive the ASCII text version
                   of the binary MAC label.  To avoid a stack error, the
                   caller must supply the textmac parameter even if the MAC
                   label's text version does not exist.  If the textmacsize
                   parameter points to zero, textmac is not dereferenced.

                   Note that there is no assurance that the binary MAC
                   stored with the object will match the binary MAC
                   generated by converting the ASCII text MAC to binary.
                   Only the binary MAC is used by the reference monitor for
                   access control decisions.

       textmacsize A pointer to the size in bytes of the text MAC label.  If
                   this parameter points to zero, dg_getomac assumes that it
                   is not to fetch the text MAC label.  If the buffer passed
                   is too small, dg_getomac stores the required size at
                   textmacsize, returns -1, and sets errno to E2BIG.

       The labsize, textmac, and textmacsize parameters are currently
       ignored.

DESCRIPTION
       The dg_getomac system call gets the MAC label for the object
       identified by targ_type and targ and copies it into the
       mac_label_struct_t structure pointed to by label.

ACCESS CONTROL
       To get the MAC label of an object, a process must have MAC read
       access to the object. When the object is a file name the process must
       also have MAC read access to the file's parent directory, and have
       search access to the file's parent directory path.

RETURN VALUE
       0      Successful completion.
       -1     An error occurred.  errno is set to indicate the error.

EXCEPTIONS
       Errno may be set to one of the following error codes:

       ENOENT        The object is a file, message queue, shared memory
                     segment or semaphore that does not exist.

       ESRCH         The object is a process that does not exist.

       ENAMETOOLONG  A component of the pathname exceeds the length limit
                     for filenames.

       EFAULT        The label parameter specified an area of memory not
                     accessible to the calling process.

       ENOMEM        The operating system was unable to allocate internal
                     memory to process the system call.

       E2BIG         The supplied buffer is too small.  The required size is
                     stored in textmacsize.

       ENOSYS        MAC is not configured on the system.

       EACCES        The caller does not have the required access rights to
                     the object.

       EOPNOTSUPP    The operation is not supported for the specified
                     targ_type.

       EDGNOATTR     The object has no MAC label.

       EINVAL        The target type targ_type parameter is not valid.

SEE ALSO
       dg_setomac(2), dg_setorange(2), dg_setomac_only(2), dg_settmpomac(2),
       dg_getorange(2), cap_defaults(5), mac_defs(5).

NOTES
       Except for directories, if a MAC range is set on a file (using
       dg_setorange), then the MAC label will be removed from the file.  If
       the MAC label is then put back on the file, the MAC range stays.


Licensed material--property of copyright holder(s)