dg_setcap(2) DG/UX B2 Security R4.12MU02 dg_setcap(2)
NAME
dgsetcap - change the capability state of a target subject or
object.
SYNOPSIS
#include <sys/capability.h>
#include <sys/dgtparms.h>
int dgsetcap(targtype, targ, select, capp)
const int targtype;
const void *targ;
const capflagt select;
capt capp;
where:
targtype A token that identifies the type of object whose
capability state is to be changed. The available tokens
are defined in sys/dgtparms.h as follows:
TPROC The object is an existing process on the system.
TFILE The object is a file identified by a pathname.
TFD The object is a file identified by a descriptor.
targ The address of the identifier of the object whose
capability state is to be changed. The value of targtype
determines the type of entity that targ points to as
follows:
TPROC targ points to a process id (type pidt).
TFILE targ points to a pathname string.
TFD targ points to a file descriptor.
select Identifies the capability set(s) in the target capability
structure to replace. The available tokens are listed
below in the DESCRIPTION section and defined in
sys/capability.h.
capp The address of the capability structure containing the
entries to replace those in the target object.
DESCRIPTION
This system call replaces selected entries in the capability
structure of the target identified by targ with corresponding entries
from the capability structure given by capp. When the target is an
object all sets are optional and may be replaced or removed based on
the value of their capp->attrs flag. See sys/capability.h for a
definition of the capp->attrs flags. When the target is a process
all sets are mandatory and can be replaced but never removed.
Capability sets are selected by setting select as follows:
DGCAPBOUNDING This flag selects the bounding capability set.
For objects, the bounding set is replaced when
DGCAPOBJHASBOUNDING is enabled in
capp->attrs; When the bounding set is selected
but its capp->attrs flag is not enabled, the
bounding set is removed.
CAPPERMITTED This flag selects the permitted capability set.
For objects, the permitted set is replaced when
DGCAPOBJHASPERMITTED is enabled in
capp->attrs; When the permitted set is
selected but its capp->attrs flag is not
enabled, the permitted set is removed.
When the target is a process the permitted set
must be a subset of the bounding set or the
call fails.
CAPINHERITABLE This flag selects the inheritable capability
set. For objects, the inheritable is replaced
when DGCAPOBJHASINHERITABLE is enabled in
capp->attrs; When the inheritable set is
selected but its capp->attrs flag is not
enabled, the inheritable set is removed.
When the target is a process the inheritable
set must be a subset of the bounding set or the
call fails.
CAPEFFECTIVE This flag selects the effective capability set
to be replaced. For objects, the effective set
is replaced when DGCAPOBJHASEFFECTIVE is
enabled in capp->attrs; When the effective set
is selected but its capp->attrs flag is not
enabled, the effective set is removed.
When the target is a process, the inheritable
and permitted sets are limited by the bounding
set, and the effective set is limited by the
resulting permitted set. This ensures that the
correct relationships between the process
capability sets is maintained.
DGCAPSELECTNONE When select is set to this value and the target
is a process, only the capp->attrs flag may be
changed. If the capp->attrs flag is the same
as the current value and the capp structure is
valid, the call succeeds without modifying the
process state.
When the target is a subject the only valid capp->attrs flags are
DGCAPSUBJSETEFFECTIVE and DGCAPALLOWCHILDSETCAP; See
sys/capability.h for valid capability attributes.
An object's capability structure is removed from the object when all
attribute flags are zero and all capability sets are removed.
When the call succeeds all sets specified by select are replaced or
removed in the target's capability structure. When the call fails
the capability structure of the target is not modified.
ACCESS CONTROL
To change the capability state of a file, the caller must own the
object and, if MAC is configured, have MAC read and write access to
the object.
To change the capability state of a process, the target process must
be the caller or the target must be the parent of the caller and have
the DGCAPALLOWCHILDSETCAP attribute enabled.
All other users require appropriate privilege.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call. 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.
The following additional restrictions apply when modifying specific
capability sets:
bounding It is not possible to increase a subject's bounding set.
Capabilities cleared from a subject's bounding set will
automatically be cleared from the permitted, effective
and inheritable sets as well.
Since an object's bounding set only serves to limit the
capabilities allowed to a new process (after exec(2)),
capabilities may be freely enabled or disabled in the
bounding set of an object.
permitted It is not possible to increase a subject's permitted set
using this call. Capabilities cleared from a subject's
permitted set will automatically be cleared from the
effective set.
Appropriate privilege required to add capabilities to an
object's permitted set.
inheritable For subjects any capability may be enabled in the
inheritable set that is also enabled in the permitted
set. It is not possible to enable a capbility in the
inheritable set which is not either already enabled in
the inheritable set, or enabled in the subject's
permitted set. Removing capabilities from the
inheritable set has no effect on the bounding, permitted
or effective sets.
Since an object's inheritable set only serves to limit
the capabilities inherited by a new process (after
exec(2)), capabilities may be freely enabled or disabled
in the inheritable set of an object.
effective Any capability may be enabled in the effective set that
is also enabled in the permitted set of the process.
Since an object's effective set only serves to limit the
capabilities enabled in the effective set of a new
process (after exec(2)), capabilities may be freely
enabled or disabled in the effective set of an object.
Note that when a process is modifying its own capability state the
value of the effective set at the beginning of the call is used to
determine the caller's capability throughout the execution of the
call.
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:
EINVAL One or more bits enabled in select are not defined for
type capflagt.
EINVAL The type, version or size field is not valid. The valid
values of these fields are: DG_CAP_DG_STATE_TYPE_0,
DG_CAP_DG_STATE_VERSION_0 and sizeof(cap_state_t)
respectively. Note that the <reserved> fields must be
0.
EINVAL The target is a process and the permitted or inheritable
set is not a subset of the bounding set.
ENOSYS This system call was made on a system that does not have
the POSIXCAP configuration option enabled.
EACCES Search permission is denied for a non-terminal component
of the targ.
EACCES MAC read or write access to the target is denied.
EPERM The caller does not have appropriate capability to set
the specified capability in the specified set.
EFAULT The parameter targ points to a memory area not
accessible to the calling process.
EFAULT The parameter capp points to a memory area not
accessible to the calling process.
ENOENT The object the pathname resolved to does not exist or a
non-terminal component does not exist.
ESRCH The process pid does not exist.
ENAMETOOLONG The pathname given by targ exceeds the length limit for
pathnames.
ELOOP The number of symbolic links encountered during pathname
resolution exceeded MAXSYMLINKS. A symbolic link cycle
is suspected.
ENOTDIR A non-terminal component of targ is not a directory.
EOPNOTSUPP The operation is not supported for the specified object.
EROFS An attempt was made to change the attributes of an
object which resides on a read-only filesystem.
ENOMEM The operating system was unable to allocate internal
memory to process the system call.
SEE ALSO
dggetcap(2), dggetrequiredcap(2), dgsetrequiredcap(2),
capdefaults(5).
Licensed material--property of copyright holder(s)