dg_dev_allocate_ctl(2) DG/UX B2 Security R4.12MU02 dg_dev_allocate_ctl(2)
NAME
dgdevallocatectl - support device allocation and deallocation
SYNOPSIS
#include <sys/dgtparms.h>
int dgdevallocatectl (path, command, arg)
char * path;
int command;
void * arg;
where:
path The name of the device node of the target device.
command One of the command options described below.
arg Information that is interpreted, or returned, based on the
command option specified by command.
DESCRIPTION
The dgdevallocatectl system call makes devices available or
unavailable for allocation and allocates and deallocates such
devices. Before a device can be allocated and used, it must be made
allocable (available for allocation) by a user with appropriate
privilege. After that, it cannot be opened unless it is first
allocated by a user.
When a user allocates a device, that user temporarily owns the device
and has exclusive access to it, until the device is deallocated and
closed. To ensure that only authorized users can gain access to an
allocable or allocated device, some operations that are normally
allowed for the owner of an object are not allowed for the temporary
owner of an allocated device. Examples of such operations include
changing the permission bits and ACL and changing the owner or group
ID.
The commands supported by this system call and their corresponding
argument, arg, are defined in <sys/dgtparms.h> and are described
below.
Commands
DGALLOWALLOCATION
Make the target device allocable. When a device is allocable, it
cannot be opened, and only the owner of the device can modify its
attributes. These restrictions cannot be overridden.
In this state, a device can be allocated by any user with read and/or
write access to the device. Explicit DAC access must be granted to
the process by the ACL on the device; DAC access overrides are not
allowed.
The ownership of the device and its initial DAC attributes (user and
group IDs, permissions, and ACLs) are determined based on the value
of arg, as follows:
DGKEEPDAC The DAC attributes of the device are not changed. That
is, the owner ID, group ID, and permissions are not
changed, and if there is an ACL, it is not removed.
DGSETDAC The DAC attributes are changed as follows:
· The owner ID is set to the caller's effective user
ID.
· The owning group ID is set to the caller's effective
group ID.
· The permissions are set to 000 (no read, write or
execute access for owner, group, or other).
While the device is in the allocable state, owner override privileges
will be ignored. That is, only processes with effective user ID
equal to the owner ID of the device can perform operations that are
restricted to the device owner. This means that only the real owner
of the device can change its access control attributes and therefore
allow or disallow users to allocate the device.
If the device is already allocable, the call succeeds without
modifying the device. The call fails if the device is not governed
by a MAC range.
The caller must have appropriate privilege, own the device, and have
MAC write access to the device.
DGDISALLOWALLOCATION
Exit from the allocable state, disallowing further allocations. If
the device is allocated, the call succeeds and the device exits from
the allocable state when it is deallocated and closed.
If the device is not allocable, the call succeeds without changing
the device state. If arg is not set to NULL, the call fails.
The caller must have appropriate privilege and MAC write access to
the device.
DGALLOCATEDEVICE
Allocate the device to the process whose ID is given by arg; when arg
is zero (0), the calling process is assumed. The device is allocated
to pid if: (1) the device is allocable, (2) is not allocated, (3) is
not open, and (4) the calling process is related to and has MAC write
access to the process given by pid. (Processes are related when
their real user IDs are equal.) When the process, pid, terminates,
the device is automatically deallocated if it is not open. If the
device is open when the process terminates, the device will be
deallocated when it is finally closed.
The access control attribute of the device are changed as follows:
· The owner ID is set to the real user ID of process pid.
· The owning group ID is set to the real group ID of the process
pid.
· The permissions are set to 0600 (owner read and write access
only).
· If the process MAC label is within the MAC range of the device,
the process label is temporarily assigned to the device. When
the process label is not within the MAC range, the temporary
label is set to either the upper or the lower bound of the MAC
range on the device, depending upon which is closer to the MAC
label of the target process.
· If the device has an extended ACL, the ACL will be temporarily
removed.
While a device is allocated, no DAC override privileges are
considered when the system performs access checks for the device.
Thus, only the owner of the device can successfully open the device.
To prevent users that can allocate a device (and become temporary
owners of the device) from giving access to users that cannot
allocate the device, the following DAC attributes cannot be changed
while the device is allocated: user ID, group ID, permission bits,
and ACL.
All attributes modified by this operation will be restored when the
device is deallocated.
The caller must have appropriate privilege, DAC read/write, and MAC
write access.
DGDEALLOCATEDEVICE
Deallocate the device identified by path so that it may be allocated
by other users. When the device is deallocated, it can be allocated
by other users, if it is still allocable. When the device is
deallocated, its attributes revert to the values present when the
device was allocated.
If the device is open, the call succeeds, but the device remains
allocated until its final close. (To forcibly deallocate a busy
device, the application with the device open must be terminated, thus
closing the device.) An implicit deallocation occurs when the
process to which the device is allocated is terminated.
If arg is not set to NULL, the call fails.
The caller must have appropriate privilege, have MAC write access to
the device, and must own the device (or have appropriate privilege to
override this restriction).
ACCESS CONTROL
For the access control requirements, see the description of each
command option.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having the specific capabilities associated
with the operation (if any) enabled in the effective capability set
of the calling process.
For the default capability for this system call, see capdefaults(5).
On systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
RETURN VALUE
0 The dgdevallocatectl operation was successful.
-1 An error occurred. errno is set to indicate the error.
DIAGNOSTICS
Errno may be set to one of the following error codes:
EACCES The caller does not have the required access to the
device given by path.
EACCES The caller does not have MAC write access to the process
pid.
EBUSY An attempt was made to make a device allocable while the
device was open.
EBUSY An attempt was made to allocate a device that was already
allocated to another user.
EFAULT The pathname parameter points to an area of memory not
accessible to the calling process.
EINVAL command or arg is not one of the valid values described
above.
EINVAL An attempt was made to allocate a device that is not
allocable.
ELOOP The number of symbolic links encountered during pathname
resolution exceeds MAXSYMLINKS. A symbolic link cycle is
suspected.
ENAMETOOLONG
The pathname exceeds the length limit for pathnames.
ENAMETOOLONG
A component of the pathname exceeds the length limit for
filenames.
ENOENT The file path resolved to does not exist.
ENOMEM There was insufficient kernel memory available to execute
command.
ENOMEM There are insufficient system resources to resolve the
pathname or expand a symbolic link.
ENOSYS An attempt was made to use this system call on a system
that does not support it.
ENOTDIR A nonterminal component of the pathname was not a
directory or symbolic link.
EOPNOTSUPP path does not point to the name of an appropriate device.
EPERM A process called dgdevallocatectl and attempted to
execute a restricted command without having appropriate
privilege.
ESRCH The process identified by pid could not be found.
SEE ALSO
admdevice(1), allocate(1), deallocate(1), appropriateprivilege(5).
Licensed material--property of copyright holder(s)