dce_acl_register_object

dce_acl_register_object_type(3sec)

Registers an ACL manager's object type

Synopsis

#include <dce/dce.h>
#include <dce/aclif.h>

void dce_acl_register_object_type(
dce_db_handle_t db,
uuid_t *mgr_type,
unsigned32 printstring_size,
sec_acl_printstring_t *printstring,
sec_acl_printstring_t *mgr_info,
sec_acl_permset_t control_perm,
sec_acl_permset_t test_perm,
dce_acl_resolve_func_t resolver,
void *resolver_arg,
unsigned32 flags,
error_status_t *status);

Parameters

Input

db
The db parameter specifies the handle to the backing store database in which the ACL objects are stored. It must be indexed by UUID and not use backing store headers. The database is obtained through dce_db_open( ), which is called prior to this routine.

mgr_type
A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them.

printstring_size
The number of items in the printstring array.

printstring
An array of sec_acl_printstring_t structures containing the printable representation of each specified permission. These are the printstrings used by dcecp or other ACL editors.

mgr_info
A single sec_acl_printstring_t containing the name and short description for the given ACL manager.

control_perm
The permission set needed to change an ACL, typically sec_acl_perm_control. If the value is 0, then anyone is allowed to change the ACL. The permission must be listed in the printstring.

test_perm
The permission set needed to test an ACL, typically sec_acl_perm_test. If the value is 0, then anyone is allowed to test the ACL. The permissions must be listed in the printstring.

resolver
The function for finding an ACL's UUID.

resolver_arg
The argument to pass to the resolver function. If using dce_acl_resolve_by_name( ) or dce_acl_resolve_by_uuid( ), then pass the database handle to the name or UUID backing store database. The backing store must use the standard backing store header. See dce_db_open(3dce).

flags
A bit mask with the following possible bit values:

dce_acl_c_orphans_ok
If this bit is specified, it is possible to replace an ACL with one in which no control bits are turned on in any of the ACL entries. (Use the rdacl_replace operation to replace an ACL.) This is a write-once operation, and once it has been done, no one can change the ACL.

dce_acl_c_has_owner
If this bit is set, then the ACL manager supports the concept of user owners of objects. This is required to use ACL entries of type user_obj and user_obj_deleg entries such as sec_acl_e_type_user_obj.

dce_acl_c_has_groups
A similar bit for group owners of objects.

Output

status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.

Description
The dce_acl_register_object_type( ) routine registers an ACL manager's object types with the ACL library.

The resolver function may be the dce_acl_resolve_by_name( ) or the dce_acl_resolve_by_uuid( ) routine, if the application uses the standard header in the backing store database, or it may be some other user-supplied routine, as appropriate. A user-supplied routine must be of type dce_acl_resolve_func_t. The resolver function finds the UUID of the ACL of the given object. The resolver's parameters must match the type dce_db_convert_func_t defined in the file <dce/aclif.h>. Observe the use of the resolver function dce_acl_convert_func( ) in Examples.

Unless the dce_acl_c_orphans_ok bit is set in the flags parameter, all ACLs must always have someone able to modify the ACL.

Another way to express this is that if dce_acl_c_orphans_ok is cleared in a call to dce_acl_register_object_type( ) where a control_perm value is specified, then a subsequent ACL replacement using an ACL that has no control bits set in any non-delegation entry will fail, resulting in the acl_s_no_control_entries error. If dce_acl_c_orphans_ok is set, but no control_perm bits are specified, then dce_acl_c_orphans_ok is ignored, and the replacement works in all cases.

Files

/usr/include/dce/aclif.h
Definition of dce_acl_resolve_func_t.

Examples
The dce_acl_register_object_type( ) routine should be called once for each type of object that the server manages. A typical call is shown below. The sample code defines three variables: the manager printstring, the ACL printstrings, and the ACL database. Note that the manager printstring does not define any permission bits; they will be set by the library to be the union of all permissions in the ACL printstring. The code also uses the global my_uuid as the ACL manager type UUID. The ACL printstring uses the standard sec_acl_perm_XXX bits.

include <dce/aclif.h>

/* Manager help. */
sec_acl_printstring_t my_acl_help = {
"me", "My manager"
};
/*
* ACL permission descriptions; these are from /usr/include/dce/aclbase.idl
* This example refrains from redefining any of the conventionally * established bits.
*/
sec_acl_printstring_t my_printstring[ ] = {
{ "r", "read", sec_acl_perm_read },
{ "f", "foobar", sec_acl_perm_unused_00000080 },
{ "w", "write", sec_acl_perm_write },
{ "d", "delete, sec_acl_perm_delete },
{ "c", "control", sec_acl_perm_control }
};

dce_db_open("my_acldb", NULL,
dce_db_c_std_header | dce_db_c_index_by_uuid,
(dce_db_convert_func_t)dce_acl_convert_func,
&dbh, &st);

dce_acl_register_object_type(dbh, &my_manager_uuid,
sizeof my_printstring / sizeof my_printstring[0],
my_printstring, &my_acl_help, sec_acl_perm_control,
0, xxx_resolve_func, NULL, 0, &st);

If the ACL manager can use the standard collection of ACL bits (that is, has not defined any special ones), then it can use the global variable dce_acl_g_printstring that predefines a printstring. Here is an example of its use:

dce_acl_register_object_type(acl_db, &your_mgr_type,
sizeof dce_acl_g_printstring / sizeof dce_acl_g_printstring[0],
dce_acl_g_printstring, &your_acl_help,
dced_perm_control, dced_perm_test, your_resolver, NULL, 0, st);

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

error_status_ok
The call was successful.

acl_s_owner_not_allowed
In a rdacl_replace operation an attempt was made to add an ACL entry of type sec_acl_e_type_user_obj or sec_acl_e_type_user_obj_deleg to a manager that does not support object users ownership.

acl_s_group_not_allowed
In a rdacl_replace operation an attempt was made to add an ACL entry of type sec_acl_e_type_group_obj or sec_acl_e_type_group_obj_deleg to a manager that does not support object group ownership.

acl_s_no_control_entries
In a rdacl_replace operation an attempt was made to replace the ACL where no entries have control permission.

acl_s_no_control_entries
In a rdacl_replace operation an attempt was made to replace the ACL where no entries have control permission. CL entry of type sec_acl_e_type_group_obj or sec_acl_e_type_group_obj_deleg to a manager that does not support object group ownership.

acl_s_no_control_entries
In a rdacl_replace operation an attempt was made to replace the ACL where no entries have control permission.

Related Information
Functions:

dce_db_open(3dce)

dce_acl_resolve_by_name(3sec)

dce_acl_resolve_by_uuid(3sec)