cap_library(3) DG/UX B2 Security R4.12MU02 cap_library(3)
NAME
cap_alias_free, cap_alias_to_set, cap_alias_to_state,
cap_get_alias_type, cap_is_alias_valid, cap_init_alias_database,
cap_no_req_state_to_alias, cap_req_state_to_alias, cap_set_to_alias,
cap_state_to_alias - capability alias routines in libtrust.a
SYNOPSIS
#include <capability.h>
typedef long * cap_alias_db_t;
int cap_alias_free ( void * cap_object )
int cap_alias_to_set ( char * cap_alias,
cap_alias_db_t db_handle,
cap_set_t * cap_set_value )
int cap_alias_to_state ( char * cap_alias,
cap_alias_db_t db_handle,
cap_t cap_state,
cap_required_t * required_cap,
cap_set_attr * cap_changes )
int cap_get_alias_type ( cap_alias_db_t db_handle,
char_ptr_type alias )
int cap_init_alias_database (
char * cap_alias_pathname,
cap_alias_db_t db_handle,
char ** error_message )
int cap_is_alias_valid ( cap_alias_db_t db_handle,
char * cap_alias )
int cap_no_req_state_to_alias (
cap_t cap_state,
cap_alias_db_t db_handle,
cap_set_alias_style_t style,
cap_alias_name_type_t name_type,
char ** cap_state_string )
int cap_req_state_to_alias (
cap_required_t * required_cap_state,
cap_alias_db_t db_handle,
cap_set_alias_style_t style,
cap_alias_name_type_t name_type,
char ** cap_state_string )
int cap_set_to_alias ( cap_set_t * cap_set,
cap_alias_db_t db_handle,
cap_set_alias_style_t style,
cap_alias_name_type_t name_type,
char ** cap_set_string )
int cap_state_to_alias ( cap_t cap_state,
cap_required_t * required_cap_state,
cap_alias_db_t db_handle,
cap_set_alias_style_t style,
cap_alias_name_type_t name_type,
char ** cap_state_string )
DESCRIPTION
This manual page describes the capability alias routines in
libtrust.a.
cap_alias_free
This function frees the resources allocated to cap_object. Valid
objects are alias database handles.
Return values:
0 The given cap_object has been freed successfully.
-1 The given cap_object was already a null pointer.
cap_alias_to_set
This function converts a capability set in string form to its binary
form, using the given initialized alias database. cap_set_value must
point to writable storage for the result.
Return values:
0 The alias is valid and was successfully converted to a
capability set.
-1 cap_alias was not found in the alias database or db_handle
does not denote a valid alias database.
cap_alias_to_state
This function converts a capability state in string form to its
binary form, using the given initialized alias database handle.
cap_state and required_cap must point to writable storage for the
result. The cap_alias may be any alias expression which would be
valid in a capability alias definition file. Incremental or
decremental syntax is allowed as well. cap_changes is a bitmask that
specifies which sets of cap_state and/or required_cap have been
modified (i.e., CAP_SET_EFFECTIVE), whether the cap_alias syntax
indicated a full or partial modification to a capability state (i.e.,
CAP_SET_PERMITTED_IS_PARTIAL), and whether the modification, if there
is one, adds or takes away capabilities from a set (i.e.,
CAP_SET_INHERITABLE_INCR).
Return values:
0 The cap_alias is valid and was successfully converted to a
capability set.
-1 The cap_alias was syntactically invalid, was not found in the
alias database or the db_handle does not denote a valid alias
database.
cap_get_alias_type
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 db_handle does not denote a valid alias database or
an error has occurred during processing.
cap_init_alias_database
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 db_handle points to NULL, a new database is created and the
db_handle is set to the handle for the new database.
If db_handle 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 error_message is non-NULL,
error_message will contain a cc-style error message of the form
"file:line message". The storage allocated to the error_message may
be deallocated by a call to free. If error_message 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
db_handle may be deallocated by calling cap_alias_free, 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.
cap_is_alias_valid
This function determines whether the given cap_alias appears in the
capability alias database.
Return values:
0 cap_alias is a valid capset or capclass alias.
-1 cap_alias is an invalid capset or capclass alias.
1 db_handle is invalid.
cap_no_req_state_to_alias
This function converts the cap_state value to its string
representation, using the given initialized alias database. This
routine is analogous to cap_state_to_alias.
Return values:
0 The capability state has been successfully converted.
-1 The db_handle does not denote a valid alias database, or style
or name_type values are invalid.
cap_req_state_to_alias
This function converts the required_cap_state value to its string
representation, using the given initialized alias database. This
routine is analogous to cap_state_to_alias.
Return values:
0 The capability state has been successfully converted.
-1 The db_handle does not denote a valid alias database, or style
or name_type are invalid.
cap_set_to_alias
This function converts cap_set to its string representation, using
the given initialized alias database handle and according to the
values of style and name_type. cap_set_string will contain the NULL-
terminated string result whose storage may later be deallocated by a
call to free(). The minimal style, CAP_SET_ALIAS_STYLE_MINIMAL, 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 name_type determines which forms of the aliases are used when
CAP_SET_ALIAS_STYLE_MINIMAL or CAP_SET_ALIAS_STYLE_EXPANDED are
specified: either the full alias (CAP_ALIAS_NAME_TYPE_FULL) or the
alias abbreviation (CAP_ALIAS_NAME_TYPE_SHORT), if there is one.
Return values:
0 The capability set has been successfully converted.
-1 The db_handle does not denote a valid alias database, or style
or name_type are invalid.
cap_state_to_alias
This function converts cap_state and required_cap_state values to
their string representation, using the given initialized alias
database. This routine is analogous to cap_set_to_alias.
Return values:
0 The capability state has been successfully converted.
-1 The db_handle does not denote a valid alias database, or style
or name_type are invalid.
EXAMPLES
The following is a sample program using several of the cap_library
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
aa_library(3), acl_library(3), audit_library(3), mac_library(3),
cap_alias_defs(4M).
Licensed material--property of copyright holder(s)