bracketing_library(3) DG/UX B2 Security R4.12MU02 bracketing_library(3)
NAME
bracketinglibrary: dgestablishusercaps,
dgestablishaugusercaps, dgestablishsystemcaps,
dgbeginusersect, dgendusersect, dgbeginaugusersect,
dgendaugusersect, dgbeginsystemsect, dgendsystemsect,
dgbeginauguserexec, dgendauguserexec, dgbeginsystemexec,
dgendsystemexec - operation bracketing routines in libtrust.a
SYNOPSIS
#include <capability.h>
int dgestablishusercaps ()
int dgestablishaugusercaps (char * optag)
int dgestablishsystemcaps ()
int dgbeginusersect ()
int dgendusersect ()
int dgbeginaugusersect (char * optag)
int dgendaugusersect ()
int dgbeginsystemsect ()
int dgendsystemsect ()
int dgbeginauguserexec (char * optag)
int dgendauguserexec ()
int dgbeginsystemexec ()
int dgendsystemexec ()
DESCRIPTION
The functions in bracketinglibrary provide support for dealing with
operation bracketing. These functions can be found in libtrust.a.
The functions fall into three different families:
dgestablishusercaps()
dgestablishaugusercaps()
dgestablishsystemcaps()
This family is used in normal, everyday, code where you know
your context. For example, you would call
dgestablishusercaps() and execute some user operations. If
you come to a system or augmented user operation, you would call
the appropriate routine. Then, for example, you might call
dgestablishusercaps() after the operation because you are
entering a section of user operations again.
dgbeginusersect()
dgendusersect()
dgbeginaugusersect()
dgendaugusersect()
dgbeginsystemsect()
dgendsystemsect()
This family is used when you need to do bracketing in a place in
the code where you do not know the context, e.g. a function that
is called from many different places, a signal handler, a
library routine, etc. These routines are used in pairs unlike
the first family above. The "begin" routines will save the
capability state before they establish the new cap state for
their type of operation. The "end" routines will restore the
capability state saved by the corresponding "begin" routine.
These routines can be nested.
dgbeginauguserexec()
dgendauguserexec()
dgbeginsystemexec()
dgendsystemexec()
This family is only used when the operation you are bracketing
performs an exec(), e.g. exec(), system(). The "begin" routines
will save the capability state before they establish the new cap
state for their type of operation. If the exec() fails, you
should call the appropriate "end" routine immediately
afterwards. This will restore the capability state before the
exec(). These routines can't be nested. You will notice there
is no dgbegin/enduserexec(). This is because these routines
manipulate the inheritable set. During normal execution, the
inheritable set will be in "user" state. The only times it
won't be is if you use one of the other routines. However, if
you call the "end" routine immediately after the exec(), the
"user" state will be re-established.
dgestablishusercaps
dgestablishusercaps() enables, in the effective set of the calling
process, the appropriate capabilities for performing user operations.
It attempts to enable all capabilities that are enabled in the
inheritable set of the calling process. All other capabilities will
be disabled in the effective set. If a capability is enabled in the
inheritable set but not in the permitted set of the calling process,
the capability will not be enabled in the effective set, but this
will not cause an error condition.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
dgestablishaugusercaps
optag is listed in the op_tag table, /etc/tcb/cap/optags. The
optag defines a capability list alias which specifies what
capabilities the system will temporarily grant to the process when
performing the operation. dgestablishaugusercaps() enables, in
the effective set of the calling process, the appropriate
capabilities for performing the augmented user operation specified by
optag. It attempts to enable all capabilities that are enabled in
the inheritable set of the calling process, plus the capabilities
associated with the specified optag. All other capabilities will be
disabled in the effective set. If a capability is enabled in the
inheritable set or is associated with the specified op_tag but is not
enabled in the permitted set of the calling process, the capability
will not be enabled in the effective set, but this will not cause an
error condition.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL optag is invalid
dgestablishsystemcaps
dgestablishsystemcaps() enables, in the effective set of the
calling process, the appropriate capabilities for performing system
operations. It will enable all capabilities that are enabled in the
permitted set of the calling process. All other capabilities will be
disabled in the effective set.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
dgbeginusersect
dgbeginusersect() saves the current effective capability set of
the calling process and then enables in the effective set of the
calling process the appropriate capabilities for performing user
operations. It attempts to enable all capabilities that are enabled
in the inheritable set of the calling process. All other
capabilities will be disabled in the effective set. If a capability
is enabled in the inheritable set but not in the permitted set of the
calling process, the capability will not be enabled in the effective
set, but this will not cause an error condition.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
NOTES
dgbeginusersect() must be used instead of dgestablishusercaps()
when bracketing is being performed in a place where you do not know
your context (e.g. library routine, signal handler). In these cases,
you are going to want to restore the capability state that existed
before you entered that section of code upon exiting. Normal in-line
code should use dgestablishusercaps().
dgbeginusersect() is meant to only be used in conjunction with
dgendusersect(). You may nest calls to dgbeginusersect() and
dgendusersect(), and the capability state restored in the
dgendusersect() call will be the state saved in the corresponding
dgbeginusersect() call.
dgendusersect
dgendusersect() makes the effective capability set of the calling
process equal to the value saved by the corresponding
dg_begin_user_sect(). If dgendusersect() is called without a
corresponding dgbeginusersect(), it will return an error.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL A corresponding call to dgbeginusersect() was not made
NOTES
dgendusersect() is meant to only be used in conjunction with
dgbeginusersect(). You may nest calls to dgbeginusersect() and
dgendusersect(), and the capability state restored in the
dgendusersect() call will be the state saved in the corresponding
dgbeginusersect() call.
dgbeginaugusersect
optag is listed in the op_tag table, /etc/tcb/cap/optags. The
optag defines a capability list alias which specifies what
capabilities the system will temporarily grant to the process when
performing the operation. dgbeginaugusersect() saves the current
effective capability set of the calling process and then enables in
the effective set of the calling process the appropriate capabilities
for performing the augmented user operation specified by optag. It
attempts to enable all capabilities that are enabled in the
inheritable set of the calling process, plus the capabilities
associated with optag. All other capabilities will be disabled in
the effective set. If a capability is enabled in the inheritable set
or is associated with optag but is not enabled in the permitted set
of the calling process, the capability will not be enabled in the
effective set, but this will not cause an error condition.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL optag is invalid
NOTES
dgbeginaugusersect() must be used instead of
dgestablishaugusercaps() when bracketing is being performed in a
place where you do not know your context (e.g. library routine,
signal handler). In these cases, you are going to want to restore
the capability state that existed before you entered that section of
code upon exiting. Normal in-line code should use
dgestablishaugusercaps().
dgbeginaugusersect() is meant to be used in conjunction with
dgendaugusersect(). You may nest calls to
dgbeginaugusersect() and dgendaugusersect(), and the
capability state restored in the dgendaugusersect() call will be
the state saved in the corresponding dgbeginaugusersect() call.
dgendaugusersect
dg_end_aug_user_sect() makes the effective capability set of the
calling process equal to the value saved by the corresponding
dg_begin_aug_user_sect(). If dg_end_aug_user_sect() is called
without a corresponding dg_begin_aug_user_sect(), it will return an
error.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL A corresponding call to dgbeginaugusersect() was not made
NOTES
dgendaugusersect() is meant to only be used in conjunction with
dgbeginaugusersect(). You may nest calls to
dgbeginaugusersect() and dgendaugusersect(), and the
capability state restored in the dgendaugusersect() call will be
the state saved in the corresponding dgbeginaugusersect() call.
dgbeginsystemsect
dg_begin_system_sect() saves the current effective capability set of
the calling process and then enables in the effective set of the
calling process the appropriate capabilities for performing system
operations. It will enable all capabilities that are enabled in the
permitted set of the calling process. All other capabilities will be
disabled in the effective set.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
NOTES
dgbeginsystemsect() must be used instead of
dgestablishsystemcaps() when bracketing is being performed in a
place where you do not know your context (e.g. library routine,
signal handler). In these cases you are going to want to restore the
capability state that existed before you entered that section of code
upon exiting. Normal in-line code should use
dgestablishsystemcaps().
dgbeginsystemsect() is meant to only be used in conjunction with
dgendsystemsect(). You may nest calls to dgbeginsystemsect()
and dgendsystemsect() and the capability state restored in the
dgendsystemsect() call will be the state saved in the
corresponding dgbeginsystemsect() call.
dgendsystemsect
dgendsystemsect() makes the effective capability set of the
calling process equal to the value saved by the corresponding
dgbeginsystemsect(). If dg_end_system_sect() is called without a
corresponding dgbeginsystemsect(), it will return an error.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL A corresponding call to dgbeginsystemsect() was not made
NOTES
dgendsystemsect() is meant to only be used in conjunction with
dgbeginsystemsect(). You may nest calls to dgbeginsystemsect()
and dgendsystemsect(), and the capability state restored in the
dgendsystemsect() call will be the state saved in the
corresponding dgbeginsystemsect() call.
dgbeginauguserexec
optag is listed in the op_tag table, /etc/tcb/cap/optags. The
optag defines a capability list alias which specifies what
capabilities the system will temporarily grant to the process when
performing the operation. dgbeginauguserexec() saves the current
inheritable capability set of the calling process and then enables in
the inheritable set of the calling process the appropriate
capabilities for performing the augmented user operation specified by
optag. It attempts to augment the inheritable capability set by
enabling in it the capabilities that are associated with optag. If
a capability is associated with optag but is not enabled in the
permitted set of the calling process, the capability will not be
enabled in the inheritable set, but this will not cause an error
condition.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL optag is invalid
NOTES
dgbeginauguserexec() should be used when the augmented user
operation being bracketed performs an exec(). If the operation does
not perform an exec(), use dgestablishaugusercaps() or
dgbeginaugusersect().
dgbeginauguserexec() is meant to only be used in conjunction with
dgendauguserexec().
dgendauguserexec
dgendauguserexec() makes the inheritable capability set of the
calling process equal to the value saved by dgbeginauguserexec().
If dgendauguserexec() is called without a corresponding
dgbeginauguserexec(), it will return an error.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL A corresponding call to dgbeginauguserexec() was not made
NOTES
dgendauguserexec() is meant to only be used in conjunction with
dgbeginauguserexec(). It will only be used in the event that the
exec() failed. You should call this routine immediately after the
exec() call fails. Therefore, it is not intended that calls to
dgbeginauguserexec() and dgendauguserexec() will be nested.
dgbeginsystemexec
dgbeginsystemexec() saves the current inheritable capability set
of the calling process and then enables in the inheritable set of the
calling process the appropriate capabilities for system operations.
It augments the inheritable capability set of the calling process by
enabling in it all capabilities that are enabled in the permitted
set.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
NOTES
dgbeginsystemexec() should be used when the system operation being
bracketed performs an exec(). If the operation does not perform an
exec(), use dgestablishsystemcaps() or dgbeginsystemsect().
dgbeginsystemexec() is meant to only be used in conjunction with
dgendsystemexec().
dgendsystemexec
dgendsystemexec() makes the inheritable capability set of the
calling process equal to the value saved by dgbeginsystemexec().
If dgendsystemexec() is called without a corresponding
dgbeginsystemexec(), it will return an error.
DIAGNOSTICS
Upon successful completion or if the system does not support the
capability feature, a value of 0 is returned. Otherwise, a value of
-1 is returned, the capability state of the calling process is
unchanged, and errno is set to one of the following values:
ENOMEM Could not allocate memory
EINVAL A corresponding call to dgbeginsystemexec() was not made
NOTES
dgendsystemexec() is meant to only be used in conjunction with
dgbeginsystemexec(). It will only be used in the event that the
exec() failed. You should call this routine immediately after the
exec() call fails. Therefore, it is not intended that calls to
dgbeginsystemexec() and dgendsystemexec() will be nested.
SEE ALSO
getcap(1), setcap(1), dggetcap(2), dgsetcap(2).
Licensed material--property of copyright holder(s)