This chapter specifies the RPC interface supporting ACL
Editors, namely the rdacl RPC interface (the corresponding
sec_acl API is specified in
Required background for this chapter appears in
This section begins with some remarks about identifying protected objects and ACLs, followed by definitions of some common data types, and the rdacl interface interspersed with commentary explaining it.
A consistent notation for these items is used throughout this section,
namely (in the order listed above):
-
-
handle_t rpc_handle;
sec_acl_component_name_t component_name;
uuid_t *manager_type;
sec_acl_type_t acl_type;
This identification scheme implies that servers supporting the
rdacl interface must uniquely identify all their ACLs by
means of such a 4-tuple. Within this constraint, however, the server's
management of its protected objects and ACLs is not further specified
here, so is application-specific.
This section specifies (in IDL/NDR) common data types and constants used by the rdacl interface (additional data types not defined in this chapter are defined in preceding chapters and in the referenced Open Group DCE 1.1 RPC Specification).
-
-
typedef [string, ptr] unsigned char *sec_acl_component_name_t;
-
-
typedef [ptr] sec_acl_t *sec_acl_p_t;
-
-
typedef struct {
unsigned32 count;
[size_is(count)] sec_acl_p_t sec_acls[];
} sec_acl_list_t;
-
-
typedef union switch (error_status_t status) {
case error_status_ok:
[ptr] sec_acl_list_t acl_list;
default:
/*empty*/ /*empty*/;
} sec_acl_result_t;
-
-
typedef [ref] twr_t *sec_acl_twr_ref_t;
-
-
typedef [ptr] struct {
unsigned32 count;
[size_is(count)] sec_acl_twr_ref_t towers[];
} *sec_acl_tower_set_t;
-
-
typedef unsigned32 sec_acl_posix_semantics_t;
const sec_acl_posix_semantics_t sec_acl_posix_no_semantics
= 0x00000000;
const sec_acl_posix_semantics_t sec_acl_posix_mask_obj
= 0x00000001;
The following values are currently registered:
ACL manager supports ACLs as described throughout DCE, with the exception that the MASK_OBJ ACLE type is not supported (that is, is not present on any ACL).
ACL manager supports ACLs as described throughout DCE (including the MASK_OBJ ACLE type).
const unsigned32 sec_acl_not_implemented = 0x17122016;
const unsigned32 sec_acl_cant_allocate_memory = 0x17122017;
const unsigned32 sec_acl_invalid_site_name = 0x17122018;
const unsigned32 sec_acl_unknown_manager_type = 0x17122019;
const unsigned32 sec_acl_object_not_found = 0x1712201a;
const unsigned32 sec_acl_no_acl_found = 0x1712201b;
const unsigned32 sec_acl_invalid_entry_name = 0x1712201c;
const unsigned32 sec_acl_expected_user_obj = 0x1712201d;
const unsigned32 sec_acl_expected_group_obj = 0x1712201e;
const unsigned32 sec_acl_invalid_entry_type = 0x1712201f;
const unsigned32 sec_acl_invalid_acl_type = 0x17122020;
const unsigned32 sec_acl_bad_key = 0x17122021;
const unsigned32 sec_acl_invalid_manager_type = 0x17122022;
const unsigned32 sec_acl_read_only = 0x17122023;
const unsigned32 sec_acl_site_read_only = 0x17122024;
const unsigned32 sec_acl_invalid_permission = 0x17122025;
const unsigned32 sec_acl_bad_acl_syntax = 0x17122026;
const unsigned32 sec_acl_no_owner = 0x17122027;
const unsigned32 sec_acl_invalid_entry_class = 0x17122028;
const unsigned32 sec_acl_unable_to_authenticate = 0x17122029;
const unsigned32 sec_acl_name_resolution_failed = 0x1712202a;
const unsigned32 sec_acl_rpc_error = 0x1712202b;
const unsigned32 sec_acl_bind_error = 0x1712202c;
const unsigned32 sec_acl_invalid_acl_handle = 0x1712202d;
const unsigned32 sec_acl_no_update_sites = 0x1712202e;
const unsigned32 sec_acl_missing_required_entry = 0x17122030;
const unsigned32 sec_acl_duplicate_entry = 0x17122031;
const unsigned32 sec_acl_bad_parameter = 0x17122032;
const unsigned32 sec_acl_not_authorized = 0x17122033;
const unsigned32 sec_acl_server_bad_state = 0x17122034;
const unsigned32 sec_acl_invalid_dfs_acl = 0x17122035;
const unsigned32 sec_acl_bad_permset = 0x17122037;
-
-
[uuid(47b33331-8000-0000-0d00-01dc6c000000), version(0.0)]
interface rdacl
{ /* begin running listing of rdacl interface */
For an explicit example of a concrete interpretation, namely in the
specific case of the RS server (whose specification is within the
scope of this document), see
The
-
-
void
rdacl_lookup (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] uuid_t *manager_type,
[in] sec_acl_type_t acl_type,
[out] sec_acl_result_t *acl_result );
The rpc_handle parameter identifies the server that manages the protected object.
The component_name parameter further identifies the protected object within the server.
The manager_type parameter identifies an ACL manager type UUID.
The acl_type parameter identifies an ACL type.
The acl_result parameter returns the result of the operation.
Required rights (suggested):
This operation succeeds only if the calling
client has "rdacl-lookup" permission (to the specified protected object,
according to the specified ACL manager's policy-see
The
-
-
void
rdacl_replace (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] uuid_t *manager_type,
[in] sec_acl_type_t acl_type,
[in] sec_acl_list_t *acl_list,
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the protected object.
The component_name parameter further identifies the protected object within the server.
The manager_type parameter identifies an ACL manager type UUID.
The acl_type parameter identifies an ACL type.
The acl_list parameter specifies the new ACLs to replace the old ACLs.
The status parameter returns the status of the operation.
Required rights (suggested):
This operation succeeds only if the calling
client has "rdacl-replace" permission (to the specified protected object,
according to the specified ACL manager's policy-see
The
-
-
void
rdacl_get_access (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] uuid_t *manager_type,
[out] sec_acl_permset_t *access_rights,
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the protected object.
The component_name parameter further identifies the protected object within the server.
The manager_type parameter identifies an ACL manager type UUID.
The access_rights parameter returns the calling client's access rights to the specified protected object. This is the client's "maximum" access rights; that is, the "union" (bitwise OR) of all the permission bits granted to the client, according to the ACLs on the protected object of ACL type sec_acl_type_object.
The status parameter returns the status of the operation.
Required rights (suggested):
This operation succeeds only if the calling
client has "rdacl-get-access" permission (to the specified protected object,
according to the specified ACL manager's policy-see
The
-
-
boolean32
rdacl_test_access (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] uuid_t *manager_type,
[in] sec_acl_permset_t access_rights,
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the protected object.
The component_name parameter further identifies the protected object within the server.
The manager_type parameter identifies an ACL manager type UUID of the protected object.
The access_rights parameter identifies the specific access rights (according to the ACLs on the protected object of ACL type sec_acl_type_object) to be tested.
The status parameter returns the status of the operation.
The boolean32 return value of this operation, which is valid only when status returns error_status_ok, returns 0 ("false") if the calling client is denied access, non-0 ("true") if the client is granted access.
Required rights (suggested):
This operation succeeds only if the calling
client has "rdacl-test-access" permission (to the specified
protected object,
according to the specified ACL manager's policy-see
The
-
-
boolean32
rdacl_place_holder_1 (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t _1_,
[in] uuid_t *_2_,
[in, ptr] sec_id_pac_t *_3_,
[in] sec_acl_permset_t _4_,
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the protected object.
The _1_ parameter has unspecified semantics.
The _2_ parameter has unspecified semantics.
The _3_ parameter has unspecified semantics.
The _4_ parameter has unspecified semantics.
The status parameter returns the status of the operation. It always returns sec_acl_not_implemented.
The boolean32 return value of this operation always returns 0 ("false").
Required rights (suggested): None.
The
-
-
void
rdacl_get_manager_types (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] sec_acl_type_t acl_type,
[in] unsigned32 count_max,
[out] unsigned32 *count,
[out] unsigned32 *num_manager_types,
[out, size_is(count_max), length_is(*count)]
uuid_t manager_types[],
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the protected object.
The component_name parameter further identifies the protected object within the server.
The acl_type parameter identifies an ACL type.
The count_max parameter identifies the maximum number of ACL manager type UUIDs to be returned (in manager_types).
The count parameter identifies the actual number of ACL manager type UUIDs returned (in manager_types).
The num_manager_types parameter identifies the total number of ACL
manager types, of ACL type acl_type, at the heads of chains
(see
The manager_types parameter is an array (of size count) of
distinct UUIDs identifying different ACL manager types protecting the
protected object (in the case of a chain of ACL managers, each
supporting <= 32 permission bits, only the first ACL manager in the
chain is returned in this way, and the rest are returned by calls to
The status parameter returns the status of the operation.
Required rights (suggested):
This operation succeeds only if the calling client
has "rdacl-get-manager-types" permission (to the specified protected
object, according to the specified server's policy (which may, in turn,
depend on the policies of the protected object's ACL managers)-see
The
-
-
void
rdacl_get_printstring (
[in] handle_t rpc_handle,
[in] uuid_t *manager_type,
[in] unsigned32 count_max,
[out] uuid_t *manager_type_next,
[out] sec_acl_printstring_t *manager_info,
[out] boolean32 *tokenize,
[out] unsigned32 *num_printstrings,
[out] unsigned32 *count,
[out, size_is(count_max), length_is(*count)]
sec_acl_printstring_t printstrings[],
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the ACL manager.
The manager_type parameter identifies an ACL manager type UUID.
The count_max parameter identifies the maximum number of printstrings to be returned (in printstrings).
The manager_type_next parameter, if not equal to uuid_nil, identifies the next ACL manager type in a linked list or "chain" of ACL manager types, which can be successively followed until the chain is exhausted (for example, such a chain can be used to support > 32 permission bits). The value uuid_nil indicates the end of this chain.
The manager_info parameter provides a name and help information
for the manager_type
ACL manager as a whole (as opposed to any of its specific
permission bits-those are described in the printstrings
parameter), as well as a complete list of all its supported permission bits
(represented as the union (bitwise OR) of all those supported bits).
The tokenize parameter identifies potential ambiguity in the
concatenation of permission printstrings (that is, in the
printstring fields of the elements of the printstrings[]
array)-when tokenize is 0 ("false"), the permission
printstrings may be concatenated into a single string without
ambiguity; when non-0 ("true"), this property does
not hold, and the permission printstrings must be "tokenised"
(that is,
separated by disambiguating characters; for example, by non-alphanumeric
characters, such as whitespace) to avoid ambiguity when concatenated.
The consumer of the tokenize parameter is typically a
user interface program (for example, an ACL editor) which wants to display
printstrings to users, and must do so unambiguously.
The num_printstrings parameter identifies the total number
(<= 32) of permission bits and
printstrings "supported" (in the sense of
The count parameter identifies the actual number of printstrings returned (in the printstrings array). In the example above, the value of count is 9.
The printstrings parameter is an array (of size count) of
printstrings returning information about the permission bits
(see manager_info above) supported by the ACL manager.
(See
The status parameter returns the status of the operation.
Required rights (suggested):
This operation succeeds only if the calling client
has "rdacl-get-printstring" permission (to the specified ACL manager,
according to the specified ACL manager's policy-see
The
-
-
void
rdacl_get_referral (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] uuid_t *manager_type,
[in] sec_acl_type_t acl_type,
[out] sec_acl_tower_set_t *tower_set,
[out] error_status_t *status );
The rpc_handle parameter identifies the server that manages the ACLs in question.
The component_name parameter further identifies a protected object within the server.
The manager_type parameter identifies an ACLE manager type UUID.
The acl_type parameter identifies an ACL type.
The tower_set parameter identifies the actual update referral information itself (represented as RPC towers, to which the client can rebind).
The status parameter returns the status of the operation.
Required rights (suggested):
This operation succeeds only if the calling
client has "rdacl-get-referral" permission (to the specified server,
according to the server's policy-see
The
-
-
void
rdacl_get_mgr_types_semantics (
[in] handle_t rpc_handle,
[in] sec_acl_component_name_t component_name,
[in] sec_acl_type_t acl_type,
[in] unsigned32 count_max,
[out] unsigned32 *count,
[out] unsigned32 *num_manager_types,
[out, size_is(count_max), length_is(*count)]
uuid_t manager_types[],
[out, size_is(count_max), length_is(*count)]
sec_acl_posix_semantics_t posix_semantics[],
[out] error_status_t *status );
} /* end running listing of rdacl interface */
The description of
The posix_semantics parameter is an array of flag words indicating the semantics that the corresponding ACL manager in the manager_types array supports.
Required rights (suggested):
This operation succeeds only if the calling client
has "rdacl-get-mgr-types-semantics" permission (to the specified protected
object, according to the specified server's policy-which may, in turn,
depend on the policies of the protected object's ACL managers-see
Typically, servers will grant this
permission to all clients (that is, no permissions are required).
Contents | Next section | Index |