cap_library(3) DG/UX B2 Security R4.12MU02 cap_library(3)
NAME
capaliasfree, capaliastoset, capaliastostate,
capgetaliastype, capisaliasvalid, capinitaliasdatabase,
capnoreqstatetoalias, capreqstatetoalias, capsettoalias,
capstatetoalias - capability alias routines in libtrust.a
SYNOPSIS
#include <capability.h>
typedef long * capaliasdbt;
int capaliasfree ( void * capobject )
int capaliastoset ( char * capalias,
capaliasdbt dbhandle,
capsett * capsetvalue )
int capaliastostate ( char * capalias,
capaliasdbt dbhandle,
capt capstate,
caprequiredt * requiredcap,
capsetattr * capchanges )
int capgetaliastype ( capaliasdbt dbhandle,
charptrtype alias )
int capinitaliasdatabase (
char * capaliaspathname,
capaliasdbt dbhandle,
char ** errormessage )
int capisaliasvalid ( capaliasdbt dbhandle,
char * capalias )
int capnoreqstatetoalias (
capt capstate,
capaliasdbt dbhandle,
capsetaliasstylet style,
capaliasnametypet nametype,
char ** capstatestring )
int capreqstatetoalias (
caprequiredt * requiredcapstate,
capaliasdbt dbhandle,
capsetaliasstylet style,
capaliasnametypet nametype,
char ** capstatestring )
int capsettoalias ( capsett * capset,
capaliasdbt dbhandle,
capsetaliasstylet style,
capaliasnametypet nametype,
char ** capsetstring )
int capstatetoalias ( capt capstate,
caprequiredt * requiredcapstate,
capaliasdbt dbhandle,
capsetaliasstylet style,
capaliasnametypet nametype,
char ** capstatestring )
DESCRIPTION
This manual page describes the capability alias routines in
libtrust.a.
capaliasfree
This function frees the resources allocated to capobject. Valid
objects are alias database handles.
Return values:
0 The given capobject has been freed successfully.
-1 The given capobject was already a null pointer.
capaliastoset
This function converts a capability set in string form to its binary
form, using the given initialized alias database. capsetvalue must
point to writable storage for the result.
Return values:
0 The alias is valid and was successfully converted to a
capability set.
-1 capalias was not found in the alias database or dbhandle
does not denote a valid alias database.
capaliastostate
This function converts a capability state in string form to its
binary form, using the given initialized alias database handle.
capstate and requiredcap must point to writable storage for the
result. The capalias may be any alias expression which would be
valid in a capability alias definition file. Incremental or
decremental syntax is allowed as well. capchanges is a bitmask that
specifies which sets of capstate and/or requiredcap have been
modified (i.e., CAPSETEFFECTIVE), whether the capalias syntax
indicated a full or partial modification to a capability state (i.e.,
CAPSETPERMITTEDISPARTIAL), and whether the modification, if there
is one, adds or takes away capabilities from a set (i.e.,
CAPSETINHERITABLEINCR).
Return values:
0 The capalias is valid and was successfully converted to a
capability set.
-1 The capalias was syntactically invalid, was not found in the
alias database or the dbhandle does not denote a valid alias
database.
capgetaliastype
This function determine the type of an alias expression.
Return values:
0 The alias expression is a caplist.
1 The alias expression is a capset.
2 The alias expression is a capclass.
3 The alias expression is invalid.
-1 The given dbhandle does not denote a valid alias database or
an error has occurred during processing.
capinitaliasdatabase
This function creates or augments an alias database by reading alias
definitions from a file. This routine checks the validity of the
capability alias definition file with the given pathname and builds
or augments a database of definitions for use by the alias conversion
routines. The routine returns 0 if the file is valid and an error
code if it is not.
If dbhandle points to NULL, a new database is created and the
db_handle is set to the handle for the new database.
If dbhandle points to an existing, valid database handle, the handle
is not modified, but the database it denotes is augmented to include
the new definitions from the given file. Note that if any aliases in
the given file already exist in the database, an error will result.
If the definition file is invalid, and errormessage is non-NULL,
errormessage will contain a cc-style error message of the form
"file:line message". The storage allocated to the errormessage may
be deallocated by a call to free. If errormessage is NULL, the
routine will not attempt to report an error message but will only
signify success or failure with the return value. Resources used by
dbhandle may be deallocated by calling capaliasfree, but calls to
conversion routines using a deallocated handle will have undefined
and potentially dangerous consequences.
Return values:
0 The file has been processed successfully, and the alias
database, if one was supplied, has been created or updated.
-1 An open, read or syntax error has occurred.
capisaliasvalid
This function determines whether the given capalias appears in the
capability alias database.
Return values:
0 capalias is a valid capset or capclass alias.
-1 capalias is an invalid capset or capclass alias.
1 dbhandle is invalid.
capnoreqstatetoalias
This function converts the capstate value to its string
representation, using the given initialized alias database. This
routine is analogous to capstatetoalias.
Return values:
0 The capability state has been successfully converted.
-1 The dbhandle does not denote a valid alias database, or style
or nametype values are invalid.
capreqstatetoalias
This function converts the requiredcapstate value to its string
representation, using the given initialized alias database. This
routine is analogous to capstatetoalias.
Return values:
0 The capability state has been successfully converted.
-1 The dbhandle does not denote a valid alias database, or style
or nametype are invalid.
capsettoalias
This function converts capset to its string representation, using
the given initialized alias database handle and according to the
values of style and nametype. capsetstring will contain the NULL-
terminated string result whose storage may later be deallocated by a
call to free(). The minimal style, CAPSETALIASSTYLEMINIMAL, may
not be truly minimal, but a form using the aliases from the database
to cover the given capability set. The algorithm uses aliases from
the database in reverse order whose values are contained in the set.
This lets an administrator arrange the order of aliases to produce
better conversions.
The nametype determines which forms of the aliases are used when
CAPSETALIASSTYLEMINIMAL or CAPSETALIASSTYLEEXPANDED are
specified: either the full alias (CAPALIASNAMETYPEFULL) or the
alias abbreviation (CAPALIASNAMETYPESHORT), if there is one.
Return values:
0 The capability set has been successfully converted.
-1 The dbhandle does not denote a valid alias database, or style
or nametype are invalid.
capstatetoalias
This function converts capstate and requiredcapstate values to
their string representation, using the given initialized alias
database. This routine is analogous to capsettoalias.
Return values:
0 The capability state has been successfully converted.
-1 The dbhandle does not denote a valid alias database, or style
or nametype are invalid.
EXAMPLES
The following is a sample program using several of the caplibrary
routines:
#include <capability.h>
main()
{
long db_handle = 0;
char * error_msg = (char*)0;
char * cap_string = (char*)0;
cap_state_t cap_state;
cap_set_t cap_set;
cap_required_t required_state;
cap_set_attr flags;
/* initialize the capability alias database */
if ( cap_init_alias_database(CAP_ALIAS_DEFS,
&db_handle,
&error_msg) == -1 )
{
printf("%s\n", error_msg);
free(error_msg);
exit(1);
}
/* convert an alias to its binary form */
if ( cap_alias_to_set("dg_cap_object_setid",
&db_handle,
&cap_set) == -1 )
{
printf("could not convert alias
\"dg_cap_object_setid\".\n");
exit(1);
}
/* convert the binary set back to its alias */
if ( cap_set_to_alias(&cap_set,
&db_handle,
CAP_SET_ALIAS_STYLE_MINIMAL,
CAP_ALIAS_NAME_TYPE_FULL,
&cap_string) == -1 )
{
printf("could not convert set to alias\n");
exit(1);
}
else
{
printf("set resolved to alias: %s\n",
cap_string);
free(cap_string);
}
/* convert a class alias to a state */
if ( cap_alias_to_state("(bound:all;permit:all;effective:all)",
&db_handle,
&cap_state,
&required_state,
&flags) == -1 )
{
printf("Alias expression
\"(bound:all;permit:all;effective:all)\"
is not valid.\n");
exit(1);
}
/* use the flags bitmask to determine
* which sets are valid in the state
*/
cap_state.attrs = 0;
if (flags & CAP_SET_EFFECTIVE)
{
cap_state.attrs = DG_CAP_OBJ_HAS_EFFECTIVE;
}
if (flags & CAP_SET_BOUNDING)
{
cap_state.attrs |= DG_CAP_OBJ_HAS_BOUNDING;
}
if (flags & CAP_SET_PERMITTED)
{
cap_state.attrs |= DG_CAP_OBJ_HAS_PERMITTED;
}
if (flags & CAP_SET_INHERITABLE)
{
cap_state.attrs |= DG_CAP_OBJ_HAS_INHERITABLE;
}
/* convert a binary state back to its
* corresponding alias string
*/
if (flags & CAP_SET_REQUIRED)
{
if ( cap_state_to_alias(
&cap_state,
&required_state,
&db_handle,
CAP_SET_ALIAS_STYLE_MINIMAL,
CAP_ALIAS_NAME_TYPE_FULL,
&cap_string) == -1 )
{
printf("could not convert state to alias\n");
exit(1);
}
else
{
printf("state resolved to alias: %s\n",
cap_string);
free(cap_string);
}
}
else
{
if ( cap_no_req_state_to_alias(
&cap_state,
&db_handle,
CAP_SET_ALIAS_STYLE_MINIMAL,
CAP_ALIAS_NAME_TYPE_FULL,
&cap_string) == -1)
{
printf("could not convert state to alias\n");
exit(1);
}
else
{
printf("state resolved to alias: %s\n",
cap_string);
free(cap_string);
}
}
cap_alias_free((void *) db_handle);
}
SEE ALSO
aalibrary(3), acllibrary(3), auditlibrary(3), maclibrary(3),
capaliasdefs(4M).
Licensed material--property of copyright holder(s)