bracketing_commands(1) DG/UX B2 Security R4.12MU02 bracketing_commands(1)
NAME
bracketing_commands: establish_user_caps, establish_aug_user_caps,
establish_system_caps, get_base_exec_caps,
establish_aug_user_exec_caps, establish_system_exec_caps,
restore_base_exec_caps, begin_user_sect, end_user_sect,
begin_aug_user_sect, end_aug_user_sect, begin_system_sect,
end_system_sect, begin_user_exec_sect, end_user_exec_sect,
begin_aug_user_exec_sect, end_aug_user_exec_sect,
begin_system_exec_sect, end_system_exec_sect - commands for
performing operation bracketing in shell scripts
SYNOPSIS
establish_user_caps
establish_aug_user_caps op_tag
establish_system_caps
get_base_exec_caps
establish_aug_user_exec_caps op_tag
establish_system_exec_caps
restore_base_exec_caps cap_set_alias
begin_user_sect
end_user_sect cap_set_alias
begin_aug_user_sect op_tag
end_aug_user_sect cap_set_alias
begin_system_sect
end_system_sect cap_set_alias
begin_user_exec_sect cap_set_alias
end_user_exec_sect cap_set_alias
begin_aug_user_exec_sect op_tag cap_set_alias
end_aug_user_exec_sect cap_set_alias
begin_system_exec_sect cap_set_alias
end_system_exec_sect cap_set_alias
DESCRIPTION
The commands described here provide support for dealing with
operation bracketing in shell scripts. The commands fall into three
different families:
establish_user_caps
establish_aug_user_caps
establish_system_caps
This family is used in normal, everyday operations that do not
perform an exec() and where you know your context. They are
analogous to the family of library routines with the same names (see
bracketing_library(3)). These command manipulate the effective set
of the process and are used for operations like shell built-ins which
do not perform an exec().
get_base_exec_caps
establish_aug_user_exec_caps
establish_system_exec_caps
restore_base_exec_caps
This family is used to bracket normal, everyday operations that
perform an exec() and where you know your context. These commands
manipulate the inheritable set of the process. If you need to use
this family of commands, you need to call get_base_exec_caps before
you do anything else. This will save the original inheritable set of
the process so you can restore it later. Whenever you come to an
augmented user or system operation, call the appropriate command.
This will change the inheritable set appropriately. When you next
encounter a user operation section (maybe right after the just-
bracketed operation), call restore_base_exec_caps and give it the
state you save in the get_base_exec_caps call. This will return the
process to the "user" state (this is why there's no
establish_user_exec_caps).
begin_user_sect
end_user_sect
begin_aug_user_sect
end_aug_user_sect
begin_system_sect
end_system_sect
This family is used when you need to do bracketing in a place in the
code where you do not know the context,such as a function that is
called from many different places. It is used to bracket operations
that do not perform an exec(). These commands are used in pairs
unlike the first two families above. The "begin" commands will save
the capability state before they establish the new cap state for
their type of operation. The "end" commands will restore the
capability state saved by the corresponding "begin" command. These
commands can be nested but it is up to the user to pass in the
appropriate cap state to the "end" calls.
begin_user_exec_sect
end_user_exec_sect
begin_aug_user_exec_sect
end_aug_user_exec_sect
begin_system_exec_sect
end_system_exec_sect
This family is used when you need to do bracketing in a place in the
code where you do no know the context, such as a function that is
called from many different places. It is used to bracket operations
that perform an exec(). These commands are used in pairs unlike the
first two families above. The "begin" commands will save the
capability state before they establish the new capability state for
their type of operation. The "end" commands will restore the
capability state saved by the corresponding "begin" command. These
commands can be nested, but it is up to the user to pass in the
appropriate capability state to the "end" calls.
establish_user_caps
The establish_user_caps command 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.
Return Value. 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 and the capability state of the calling
process is unchanged.
Note. The establish_user_caps command can only be used to bracket
user operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. To bracket user operations that perform an
exec(), use begin_user_exec_sect.
establish_aug_user_caps
The op_tag argument is listed in the op_tag table,
/etc/tcb/cap/op_tags. The op_tag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation.
establish_aug_user_caps enbales, in the effective set of the calling
process, the appropriate capabilities for performing the augmented
user operation specified by op_tag. It attempts to enable all
capabilities that are enabled in the inheritable set of the calling
process plus the capabilities associated with op_tag. All other
capabilities will be disabled in the effective set. If a capability
is enabled in the inheritable set or is associated with 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.
Example.
establish_aug_user_caps DG_OT_FOOBAR
Enables, in the effective set, all capabilities associated with the
DG_OT_FOOBAR op_tag, provided they are also in the permitted set.
File.
/etc/tcb/cap/op_tags Table of op_tags.
Return Value. 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 and the capability state of the calling
process is unchanged.
Note. The establish_aug_user_caps command can only be used to
bracket augmented user operations that are built-in shell operations
(operations that do not perform an exec()) because it manipulates the
process' effective capability set. If you want to bracket augmented
user operations that perform an exec() you must use
establish_aug_user_exec_caps or begin_aug_user_exec_sect.
establish_system_caps
The establish_system_caps command 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.
Return Value. 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 and the capability state of the calling
process is unchanged.
Note. The establish_system_caps command can only be used to bracket
system operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. If you want to bracket system operations
that perform an exec() you must use establish_system_exec_caps or
begin_system_exec_sect.
get_base_exec_caps
The get_base_exec_caps command prints the alias representing the
inheritable capability set of the calling process to standard output.
Return Value. The alias representing the inheritable capability set
of the calling process is printed to standard output. 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.
Note. This command will not print anything to standard output on a
system on which the capability feature is not supported.
establish_aug_user_exec_caps
The op_tag argument is listed in the op_tag table,
/etc/tcb/cap/op_tags. The op_tag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation. The
establish_aug_user_exec_caps command attempts to augment the
inheritable capability set of the calling process by enabling in it
the capabilities that are associated with op_tag. If a capability is
associated with op_tag 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.
Example.
establish_aug_user_exec_caps DG_OT_FOOBAR
Enables, in the inheritable set, all capabilities associated with the
DG_OT_FOOBAR op_tag, provided they are also in the permitted set.
File.
/etc/tcb/cap/op_tags Table of op_tags.
Return Value. 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 and the capability state of calling process
is unchanged.
Note. The establish_aug_user_exec_caps command can only be used to
bracket augmented user operations that perform an exec() (e.g. a
shell command) because it manipulates the process' inheritable
capability set. If you want to bracket augmented user operations
that do not perform an exec() you must use establish_aug_user_caps or
begin_aug_user_sect.
establish_system_exec_caps
The establish_system_exec_caps shell command will augment the
inheritable capability set of the calling process by enabling all
capabilities that are enabled in its permitted set.
Return Value. 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 and the capability state of the calling
process is unchanged.
Note. The establish_system_exec_caps command can only be used to
bracket system operations that perform an iexec() (e.g. a shell
command) because it manipulates the process' inheritable capability
set. If you want to bracket system operations that do not perform an
exec() you must use establish_system_caps or begin_system_sect.
restore_base_exec_caps
The base capability state cap_set_alias is acquired by a call to
get_base_exec_caps. The restore_base_exec_caps command makes the
inheritable capability set of the calling process equal to the value
passed in as cap_set_alias. This value should be the result of a
previous call to get_base_exec_caps.
Return Value. 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 and the capability state of the calling
process is unchanged.
Note. The restore_base_exec_caps command will accept any capability
set alias as cap_set_alias but it is meant to only be used with the
value from a previous get_base_exec_caps call.
begin_user_sect
The begin_user_sect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also enables, in the effective capability 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.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_user_sect command can only be used to bracket user
operations that are built-in shell operations (operations that do not
perform an exec()) because it manipulates the process' effective
capability set. If you want to bracket user operations that perform
an exec() you must use begin_user_exec_sect.
The begin_user_sect command must be used instead of
establish_user_caps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). 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 establish_user_caps.
The begin_user_sect command is meant to only be used in conjunction
with end_user_sect. You may nest calls to begin_user_sect and
end_user_sect and the capability state restored in the end_user_sect
call will be the state saved in the corresponding begin_user_sect
call.
end_user_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_user_sect. The end_user_sect command
makes the effective capability set of the calling process equal to
the value passed in as cap_set_alias. This value should be the
result of the corresponding call to begin_user_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_user_sect command will accept any capability set
alias as cap_set_alias but it is meant to only be used with the value
from a previous begin_user_sect call.
The end_user_sect command is meant to only be used in conjunction
with begin_user_sect. You may nest calls to begin_user_sect and
end_user_sect and the capability state restored in the end_user_sect
call will be the state saved in the corresponding begin_user_sect
call.
begin_aug_user_sect
The op_tag argument is listed in the op_tag table,
/etc/tcb/cap/op_tags. The op_tag argument defines a capability list
alias which specifies what capabilities the system will temporarily
grant to the process when performing the operation. The
begin_aug_user_sect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also enables, in the effective set of the calling process, the
appropriate capabilities for performing the augmented user operation
specified by op_tag. It attempts to enable all capabilities that are
enabled in the inheritable set of the calling process plus the
capability associated with op_tag. All other capabilities will be
disabled in the effective set. If a capability is enabled in the
inheritable set or associated with op_tag 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.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_aug_user_sect command can only be used to bracket augmented
user operations that are built-in shell operations (operations that
do not perform an exec()) because it manipulates the process'
effective capability set. If you want to bracket augmented user
operations that perform an exec() you must use
establish_aug_user_exec_caps or begin_aug_user_exec_sect.
The begin_aug_user_sect command must be used instead of
establish_aug_user_caps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). 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 establish_aug_user_caps.
The begin_aug_user_sect command is meant to only be used in
conjunction with end_aug_user_sect. You may nest calls to
begin_aug_user_sect and end_aug_user_sect and the capability state
restored in the end_aug_user_sect call will be the state saved in the
corresponding begin_user_sect call.
end_aug_user_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_aug_user_sect. The end_aug_user_sect
command makes the effective capability set of the calling process
equal to the value passed in as cap_set_alias. This value should be
the result of the corresponding call to begin_aug_user_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_aug_user_sect command will accept any capability set
alias as cap_set_alias but it is meant to only be used with the value
from a previous begin_aug_user_sect call.
The end_aug_user_sect command is meant to only be used in conjunction
with begin_aug_user_sect. You may nest calls to begin_aug_user_sect
and end_aug_user_sect and the capability state restored in the
end_aug_user_sect call will be the state saved in the corresponding
begin_aug_user_sect call.
begin_system_sect
The begin_system_sect command prints an ASCII string representing the
effective capability set of the calling process to standard output.
It also 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.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_system_sect command can only be used to bracket system
operations that are built-in shell operations (operations that do not
perform an exec()) because it manipulates the process' effective
capability set. If you want to bracket system operations that
perform an exec() you must use establish_system_exec_caps or
begin_system_exec_sect.
The begin_system_sect command must be used instead of
establish_system_caps when bracketing is being performed in a place
where you do not know your context (e.g. shell function). 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 establish_system_caps.
The begin_system_sect command is meant to only be used in conjunction
with end_system_sect. You may nest calls to begin_system_sect and
end_system_sect and the capability state restored in the
end_system_sect call will be the state saved in the corresponding
begin_system_sect call.
end_system_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_system_sect. The end_system_sect command
makes the effective capability set of the calling process equal to
the value passed in as cap_set_alias. This value should be the
result of the corresponding call to begin_system_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_system_sect command will accept any capability set
alias as cap_set_alias but it is meant to only be used with the value
from a previous begin_system_sect call.
The end_system_sect command is meant to only be used in conjunction
with begin_system_sect. You may nest calls to begin_system_sect and
end_system_sect and the capability state restored in the
end_system_sect call will be the state saved in the corresponding
begin_system_sect call.
begin_user_exec_sect
The capability set value cap_set_alias is obtained by the
corresponding call to get_base_exec_caps. The begin_user_exec_sect
command prints an ASCII string representing the inheritable
capability set of the calling process to standard output. It also
makes the inheritable capability set equal to the result of a
previous call to get_base_exec_caps (passed in as cap_set_alias), in
order to perform user operations. If begin_user_exec_sect is called
without a corresponding get_base_exec_caps call, it will return an
error.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_user_exec_sect command can only be used to bracket user
operations that perform an exec() (e.g. a shell command) because it
manipulates the process' inheritable capability set. If you want to
bracket user operations that do not perform an exec() you must use
establish_user_caps or begin_user_sect.
The begin_user_exec_sect command must be used when bracketing is
being performed in a place where you do not know your context (e.g.
shell function). In these cases you are going to want to restore the
capability state that existed before you entered that section of code
upon exiting.
The begin_user_exec_sect command is meant to only be used in
conjunction with end_user_exec_sect. You may nest calls to
begin_user_exec_sect and end_user_exec_sect and the capability state
restored in the end_user_exec_sect call will be the state saved in
the corresponding begin_user_exec_sect call.
end_user_exec_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_user_exec_sect. The end_user_exec_sect
command makes the inheritable capability set of the calling process
equal to the value passed in as cap_set_alias. This value should be
the result of the corresponding call to begin_user_exec_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_user_exec_sect command will accept any capability set
alias as cap_set_alias but it is meant to only be used with the value
from a previous begin_user_exec_sect call.
The end_user_exec_sect command is meant to only be used in
conjunction with begin_user_exec_sect. You may nest calls to
begin_user_exec_sect and end_user_exec_sect and the capability state
restored in the end_user_exec_sect call will be the state saved in
the corresponding begin_user_exec_sect call.
begin_aug_user_exec_sect
The op_tag argument is listed in the op_tag table,
/etc/tcb/cap/op_tags. The op_tag defines a capability list alias
which specifies what capabilities the system will temporarily grant
to the process when performing the operation. The capability set
value cap_set_alias is obtained by the corresponding call to
get_base_exec_caps. The begin_aug_user_exec_sect command prints an
ASCII string representing the inheritable capability set of the
calling process to standard output. It also makes the inheritable
capability set equal to the result of a previous call to
get_base_exec_caps (passed in as cap_set_alias) plus the capabilities
that are associated with the specified op_tag.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_aug_user_exec_sect command can only be used to bracket
augmented user operations that perform an exec() (e.g. a shell
command) because it manipulates the process' inheritable capability
set. If you want to bracket augmented user operations that do not
perform an exec() you must use establish_aug_user_caps or
begin_aug_user_sect.
The begin_aug_user_exec_sect command must be used instead of
establish_aug_user_exec_caps when bracketing is being performed in a
place where you do not know your context (e.g. shell function). 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 establish_aug_user_exec_caps.
The begin_aug_user_exec_sect command is meant to only be used in
conjunction with end_aug_user_exec_sect. You may nest calls to
begin_aug_user_exec_sect and end_aug_user_exec_sect and the
capability state restored in the end_aug_user_exec_sect call will be
the state saved in the corresponding begin_aug_user_exec_sect call.
end_aug_user_exec_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_aug_user_exec_sect. The
end_aug_user_exec_sect command makes the inheritable capability set
of the calling process equal to the value passed in as cap_set_alias.
This value should be the result of the corresponding call to
begin_aug_user_exec_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_aug_user_exec_sect command will accept any capability
set alias as cap_set_alias but it is meant to only be used with the
value from a previous begin_aug_user_exec_sect call.
The end_aug_user_exec_sect command is meant to only be used in
conjunction with begin_aug_user_exec_sect. You may nest calls to
begin_aug_user_exec_sect and end_aug_user_exec_sect and the
capability state restored in the end_aug_user_exec_sect call will be
the state saved in the corresponding begin_aug_user_exec_sect call.
begin_system_exec_sect
The capability set value cap_set_alias is obtained by the
corresponding call to get_base_exec_caps. The begin_system_exec_sect
command prints an ASCII string representing the inheritable
capability set of the calling process to standard output. It also
makes the inheritable capability set equal to the result of a
previous call to get_base_exec_caps (passed in as cap_set_alias) plus
the capability that are enabled in the permitted set.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. This command will not print anything to standard output on a
system that does not support the capability feature.
The begin_system_exec_sect command can only be used to bracket system
operations that perform an exec() (e.g. a shell command) because it
manipulates the process' inheritable capability set. If you want to
bracket system operations that do not perform an exec() you must use
establish_system_caps or begin_system_sect.
The begin_system_exec_sect command must be used instead of
establish_system_exec_caps when bracketing is being performed in a
place where you do not know your context (e.g. shell function). 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 establish_system_exec_caps.
The begin_system_exec_sect command is meant to only be used in
conjunction with end_system_exec_sect. You may nest calls to
begin_system_exec_sect and end_system_system_sect and the capability
state restored in the end_system_exec_sect call will be the state
saved in the corresponding begin_system_exec_sect call.
end_system_exec_sect
The capability set value cap_set_alias is obtained by the
corresponding call to begin_system_exec_sect. The
end_system_exec_sect command makes the effective capability set of
the calling process equal to the value passed in as cap_set_alias.
This value should be the result of the corresponding call to
begin_system_exec_sect.
Return Value. 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 and the capability state of the calling
process is unchanged.
Notes. The end_system_exec_sect command will accept any capability
set alias as cap_set_alias but it is meant to only be used with the
value from a previous begin_system_exec_sect call.
The end_system_exec_sect command is meant to only be used in
conjunction with begin_system_exec_sect. You may nest calls to
begin_system_exec_sect and end_system_exec_sect and the capability
state restored in the end_system_exec_sect call will be the state
saved in the corresponding begin_system_exec_sect call.
SEE ALSO
getcap(1), setcap(1), bracketing_library(3).
Licensed material--property of copyright holder(s)