Previous section.

DCE 1.1: Authentication and Security Services
Copyright © 1997 The Open Group

RS Editor RPC Interfaces

This chapter specifies the RPC interfaces supporting RS (or Registry) Editors. These interfaces are:

The APIs that correspond to these RPC interfaces are specified in Registry API .

Recall that, by definition, RS Editors are just RPC clients that invoke the operations defined in this chapter to access and manipulate (via the RS server and its ACL managers) the RS datastore items. (See Registration Service (RS) and RS Editors for background.)

Note that the RS supports some RPC interfaces other than those specified in this chapter (they are specified in subsequent chapters).

RS Protected Objects and their ACL Manager Types

The RS regards its datastore items as protected objects, so it supports the rdacl RPC interface, and its ACLs can be managed via ACL Editors. The RS supports seven kinds of protected objects, each of which is managed by a single ACL Manager Type (see Registration Service (RS) and RS Editors ).

For DCE 1.1 (and newer versions), the RS ACL Managers have been enhanced to support generic "attribute persmssions" that (cell) administrators may assign for access control for attribute types of their choice. The set of new permission bits in the set {O, P, Q, ..., X, Y, Z} are supported by the ACL Manager for each registry object type that supports Extended Registry Attributes (ERAs). In other words, the list of valid permissions for each ACL Manager type listed in ACL Permissions Supported by RS has been augmented with the `O' through `Z' permission bits. All uses of these additional attribute permission bits:

will be controlled by the cell administrator. The DCE security services will not interpret or assign meaning to these bits other than what is implied by their inclusion in a schema entry.

Information on Extended Registry Attributes can be found in Extended Registry Attribute Facility .

The ACL Manager Type UUIDs of these five ACL Managers are as follows:


Manager Type ACL Manager Type UUID
Policy 06ab8f10-0191-11ca-a9e8-08001e039d7d
Directory 06ab9c80-0191-11ca-a9e8-08001e039d7d
Principal 06ab9320-0191-11ca-a9e8-08001e039d7d
Group 06ab9640-0191-11ca-a9e8-08001e039d7d
Organisation 06ab9960-0191-11ca-a9e8-08001e039d7d
Replist 2ac24970-60c3-11cb-b261-08001e039d7d
Attr_schema 755cd9ce-ded3-11cc-8d0a-080009353559


Table: ACL Managers Supported by RS

The permissions supported by the RS's ACL Managers are as follows (see also Implementation Variability Regarding Required Rights ). Note that those marked with "ERA" are supported as generic permissions only:


Manager Type Supported Permissions
  r c i d t D n f m a u g M A I {O-Z}
Policy r c             m a       A   ERA
Directory r c i d   D n                 ERA
Principal r c       D n f m a u g       ERA
Group r c     t D n f m       M     ERA
Organization r c     t D n f m       M     ERA
Replist   c i d         m         A I ERA
Attr_schema r c i d         m       M     ERA


Table: ACL Permissions Supported by RS

The ACLE Types supported by the RS's ACL Managers are as follows:

This is illustrated in the following two tables:


Manager Type Supported ACLE Types
  UO U GO G O FU FG FO AO UN E
Policy   U   G O FU FG FO AO UN E
Directory   U   G O FU FG FO AO UN E
Principal UO U   G O FU FG FO AO UN E
Group   U GO G O FU FG FO AO UN E
Organization   U   G O FU FG FO AO UN E
Replist   U   G O FU FG FO AO UN E
Attr_schema   U   G O FU FG FO AO UN E


Table: ACLE Types Supported by RS

The meanings of the abbreviations of the ACLE types given in this and the preceeding table can be found in the representation of the sec_acl_entry_type_t data type in ACLE Types .


Manager Type Supported Delegation ACLE Types
  UOD UD FUD GOD GD FGD OD FOD AOD    
Policy UOD UD FUD GOD GD FGD OD FOD AOD    
Directory UOD UD FUD GOD GD FGD OD FOD AOD    
Principal UOD UD FUD GOD GD FGD OD FOD AOD    
Group UOD UD FUD GOD GD FGD OD FOD AOD    
Organization UOD UD FUD GOD GD FGD OD FOD AOD    
Replist UOD UD FUD GOD GD FGD OD FOD AOD    
Attr_schema UOD UD FUD GOD GD FGD OD FOD AOD    


Table: Delegation ACLE Types Supported by RS

Supported Permissions

The printstrings, bit representations and semantics of the supported permissions (listed in ACL Permissions Supported by RS ) are specified as follows (see also Implementation Variability Regarding Required Rights ):

The RS's Directory ACL Manager (which is the only one of the seven RS ACL Managers that supports container objects) supports the inheritance model specified in Object Types, ACL Types, and ACL Inheritance .

The required rights for successful invocation of RS RPC interface operations (and therefore of the routines based on them) are specified in context in the remaining sections of this chapter.

Common Data Types and Constants for RS Editors

This section specifies (in IDL/NDR) common data types and constants used in the RS's RPC interfaces.

bitset

The bitset data type represents a 32-bit flag word.

typedef unsigned32 bitset;

sec_timeval_sec_t

The sec_timeval_sec_t data type represents the number of seconds elapsed since the epoch 00:00.00 January 1, 1970 AD.

typedef signed32 sec_timeval_sec_t;

sec_timeval_t

The sec_timeval_t data type consists of a structure containing the full UNIX time. The structure contains two 32-bit integers that indicate seconds (sec) and microseconds (usec) since 00:00.00 January 1, 1970 AD.

typedef struct { signed32 sec; signed32 usec; } sec_timeval_t;

sec_rgy_name_t-Short and Long PGO Names

The sec_rgy_name_t data type represents stringnames, usually short PGO names in the RS-supported PGO namespaces (on occasion, as in rs_bind_get_update_site() , this data type is used to indicate names other than short PGO names). These short PGO names are also called security-(domain-)relative names, indicating that they are subordinate to a specified PGO naming domain, of type sec_rgy_domain_t, as specified in sec_rgy_domain_t . They are the names that appear at the level of the RPC interfaces supported by RS Editors.

const signed32 sec_rgy_name_max_len = 1024; const signed32 sec_rgy_name_t_size = 1025; typedef [string] char sec_rgy_name_t[sec_rgy_name_t_size];

The syntax of sec_rgy_name_t is the same as the CDS naming syntax (as specified in the referenced Open Group DCE 1.1 Directory Services Specification), with the additional stipulation that these names always have length in the interval [1, 1024]. In particular, a short PGO name cannot begin or end with the character / (slash).

In all applications where a sec_rgy_name_t occurs, the context of a PGO naming domain must also be indicated, explicitly or implicitly. Then, a long PGO name (or security-relative name) may be formed by prepending the stringname associated with the PGO domain to the short PGO name (sec_rgy_name_t), separated by a / (slash).

For example, the short PGO name foo/bar in the context of the PGO principal domain (sec_rgy_domain_person, which has associated stringname person-see sec_rgy_domain_t ), yields the long PGO name person/foo/bar. (And then this would further appear in the global namespace, via the junction architecture (.cX acl_editors ), as the name /.../name-of-server/person/foo/bar -for example, as /.../name-of-cell/sec/person/foo/bar.)

sec_rgy_pname_t

The sec_rgy_pname_t data type represents printable stringnames.

const signed32 sec_rgy_pname_max_len = 256; const signed32 sec_rgy_pname_t_size = 257; typedef [string] char sec_rgy_pname_t[sec_rgy_pname_t_size];

The characters of sec_rgy_pname_t are to be taken from the DCE Portable Character Set.

sec_rgy_login_name_t

The sec_rgy_login_name_t data type represents (the name of) an account.

typedef struct { sec_rgy_name_t pname; sec_rgy_name_t gname; sec_rgy_name_t oname; } sec_rgy_login_name_t;

Its fields are the following:

sec_rgy_cursor_t

The sec_rgy_cursor_t data type is used as a datastore cursor (that is, a position indicator) for incremental operations in the RS datastore.

typedef struct { uuid_t source; signed32 position; boolean32 valid; } sec_rgy_cursor_t;

Its fields are the following:

rs_cache_data_t

The rs_cache_data_t data type represents RS datastore modification time information. This information is intended to be used by RS Editor clients to manage their caches of RS datastore information they may maintain.

Note:
Maintaining a cache, as well as the details of its maintenance, is implementation-specific, and so is not further specified by DCE.
typedef struct { uuid_t site_id; sec_timeval_sec_t person_dtm; sec_timeval_sec_t group_dtm; sec_timeval_sec_t org_dtm; } rs_cache_data_t;

Its fields are the following (see sec_rgy_domain_t and sec_rgy_pgo_item_t for definitions of terms used here):

Note:
The dtm (date/time modified) information conveyed by the rs_cache_data_t data type is fairly coarse-grained, but since PGO nodes are only infrequently modified, a more sophisticated caching scheme is not considered necessary.

sec_rgy_handle_t

The sec_rgy_handle_t data type represents a pointer to a RS server handle. The RS server is bound to a handle with the sec_rgy_site_open() routine.
typedef void *sec_rgy_handle_t;

The rs_bind RPC Interface

This section specifies (in IDL/NDR) the RS's rs_bind RPC interface.

Common Data Types and Constants for rs_bind

The following are common data types and constants used in the rs_bind interface.

rs_replica_name_p_t

The rs_replica_name_p_t data type represents the (cell-relative) RPC binding stringname of an RS server.

typedef [string] unsigned char *rs_replica_name_p_t;
rs_replica_twr_vec_p_t

The rs_replica_twr_vec_p_t data type represents a vector of (pointers to) RPC protocol towers.

typedef struct { unsigned32 num_towers; [size_is(num_towers)] twr_p_t towers[]; } rs_replica_twr_vec_t, *rs_replica_twr_vec_p_t;

Its fields are the following:

Interface UUID and Version Number for rs_bind

The interface UUID and version number for the rs_bind interface are given by the following:

[ uuid(d46113d0-a848-11cb-b863-08001e046aa5), version(2.0), pointer_default(ptr) ] interface rs_bind { /* begin running listing of rs_bind interface */

rs_bind_get_update_site()

The rs_bind_get_update_site() operation returns binding information for an update RS server (as opposed to a query server).

void rs_bind_get_update_site ( [in] handle_t rpc_handle, [out] sec_rgy_name_t cellname, [out] boolean32 *update_site, [out] rs_replica_name_p_t *update_site_name, [out] uuid_t *update_site_id, [out] rs_replica_twr_vec_p_t *update_site_twrs, [out] error_status_t *status ); }

The rpc_handle parameter identifies the RS server (called the bound server in this section).

The cellname parameter indicates the bound server's cell.

The update_site parameter indicates whether the bound server is an update server or not: if non-0 (TRUE), the bound server is an update server; if 0 (FALSE), it is only a query (non-update) server.

The update_site_name parameter indicates the cell-relative RS binding stringname (relative to the cell cellname) of an update server in the cell cellname.

The semantics of the update_site_id parameter are unspecified in this revision of DCE.

Note:
It is intended that update_site_id indicates the object UUID of an update server replica in the cell cellname, but this notion is specific to the replication model, which is not specified in this revision of DCE (it is intended for inclusion in a future revision). (The notion of object UUID of update server replica is not be confused with the RS's object UUID in the sense of RPC, which is registered in the CDS namespace, and which represents all replicas, not just this update server replica.)

The update_site_twrs parameter indicates the protocol tower set of an update server in the cell cellname.

The status parameter returns the status of the operation.

Required rights: None.

The rs_policy RPC Interface

This section specifies (in IDL/NDR) the RS's rs_policy RPC interface.

Common Data Types and Constants for rs_policy

The following are common data types and constants used in the rs_policy interface.

sec_timeval_period_t

The sec_timeval_period_t data type measures time intervals in seconds.

typedef signed32 sec_timeval_period_t;
sec_rgy_properties_flags_t

The sec_rgy_properties_flags_t data type is a flag word representing attributes of an RS server/datastore.

typedef bitset sec_rgy_properties_flags_t; const unsigned32 sec_rgy_prop_readonly = 0x1; const unsigned32 sec_rgy_prop_auth_cert_unbound = 0x2; const unsigned32 sec_rgy_prop_shadow_passwd = 0x4; const unsigned32 sec_rgy_prop_embedded_unix_id = 0x8;

The following values are currently registered:

sec_rgy_properties_t

The sec_rgy_properties_t data type represents the attributes of the RS's Policy item.

typedef struct { signed32 read_version; signed32 write_version; sec_timeval_period_t minimum_ticket_lifetime; sec_timeval_period_t default_certificate_lifetime; unsigned32 low_unix_id_person; unsigned32 low_unix_id_group; unsigned32 low_unix_id_org; unsigned32 max_unix_id; sec_rgy_properties_flags_t flags; sec_rgy_name_t realm; uuid_t realm_uuid; signed32 unauthenticated_quota; } sec_rgy_properties_t;

Its fields are the following:

sec_rgy_plcy_pwd_flags_t

The sec_rgy_plcy_pwd_flags_t data type is a flag word indicating password policy restrictions.

typedef bitset sec_rgy_plcy_pwd_flags_t; const unsigned32 sec_rgy_plcy_pwd_no_spaces = 0x1; const unsigned32 sec_rgy_plcy_pwd_non_alpha = 0x2;

The following values are currently registered:

sec_rgy_plcy_t

The sec_rgy_plcy_t data type represents an organisation's policy information (or that of the cell).

typedef struct { signed32 passwd_min_len; sec_timeval_period_t passwd_lifetime; sec_timeval_sec_t passwd_exp_date; sec_timeval_period_t acct_lifespan; sec_rgy_plcy_pwd_flags_t passwd_flags; } sec_rgy_plcy_t;

Its fields are the following:

sec_rgy_plcy_auth_t

The sec_rgy_plcy_auth_t data type represents cell-wide authentication policy.

typedef struct { sec_timeval_period_t max_ticket_lifetime; sec_timeval_period_t max_renewable_lifetime; } sec_rgy_plcy_auth_t;

Its fields are the following:

Status Codes

The following status codes (transmitted as values of the type error_status_t) are specified for the RS editor interfaces. Only their values and a short one-line description of them are specified here-their detailed usage is specified in context elsewhere in this chapter.

Values:

const unsigned32  sec_rgy_not_implemented         = 0x17122073;
const unsigned32  sec_rgy_bad_domain              = 0x17122074;
const unsigned32  sec_rgy_object_exists           = 0x17122075;
const unsigned32  sec_rgy_name_exists             = 0x17122076;
const unsigned32  sec_rgy_unix_id_changed         = 0x17122077;
const unsigned32  sec_rgy_is_an_alias             = 0x17122078;
const unsigned32  sec_rgy_no_more_entries         = 0x17122079;
const unsigned32  sec_rgy_object_not_found        = 0x1712207a;
const unsigned32  sec_rgy_server_unavailable      = 0x1712207b;
const unsigned32  sec_rgy_not_member_group        = 0x1712207c;
const unsigned32  sec_rgy_not_member_org          = 0x1712207d;
const unsigned32  sec_rgy_not_member_group_org    = 0x1712207e;
const unsigned32  sec_rgy_incomplete_login_name   = 0x1712207f;
const unsigned32  sec_rgy_passwd_invalid          = 0x17122080;
const unsigned32  sec_rgy_not_authorized          = 0x17122081;
const unsigned32  sec_rgy_read_only               = 0x17122082;
const unsigned32  sec_rgy_bad_alias_owner         = 0x17122083;
const unsigned32  sec_rgy_bad_data                = 0x17122084;
const unsigned32  sec_rgy_cant_allocate_memory    = 0x17122085;
const unsigned32  sec_rgy_dir_not_found           = 0x17122086;
const unsigned32  sec_rgy_dir_not_empty           = 0x17122087;
const unsigned32  sec_rgy_bad_name                = 0x17122088;
const unsigned32  sec_rgy_dir_could_not_create    = 0x17122089;
const unsigned32  sec_rgy_dir_move_illegal        = 0x1712208a;
const unsigned32  sec_rgy_quota_exhausted         = 0x1712208b;
const unsigned32  sec_rgy_foreign_quota_exhausted = 0x1712208c;
const unsigned32  sec_rgy_no_more_unix_ids        = 0x1712208d;
const unsigned32  sec_rgy_uuid_bad_version        = 0x1712208e;
const unsigned32  sec_rgy_key_bad_version         = 0x1712208f;
const unsigned32  sec_rgy_key_version_in_use      = 0x17122090;
const unsigned32  sec_rgy_key_bad_type            = 0x17122091;
const unsigned32  sec_rgy_crypt_bad_type          = 0x17122092;
const unsigned32  sec_rgy_bad_scope               = 0x17122093;
const unsigned32  sec_rgy_object_not_in_scope     = 0x17122094;
const unsigned32  sec_rgy_cant_authenticate       = 0x17122095;
const unsigned32  sec_rgy_alias_not_allowed       = 0x17122096;
const unsigned32  sec_rgy_bad_chksum_type         = 0x17122097;
const unsigned32  sec_rgy_bad_integrity           = 0x17122098;
const unsigned32  sec_rgy_key_bad_size            = 0x17122099;
const unsigned32  sec_rgy_mkey_cant_read_stored   = 0x1712209a;
const unsigned32  sec_rgy_mkey_bad_stored         = 0x1712209b;
const unsigned32  sec_rgy_mkey_bad                = 0x1712209c;
const unsigned32  sec_rgy_bad_handle              = 0x1712209d;
const unsigned32  sec_rgy_s_pgo_is_required       = 0x1712209e;
const unsigned32  sec_rgy_host_context_not_avail  = 0x1712209f;
const unsigned32  sec_rgy_mkey_file_io_failed     = 0x171220a0;
const unsigned32  sec_rgy_tower_rebind_failed     = 0x171220a1;
const unsigned32  sec_rgy_site_not_absolute       = 0x171220a2;
const unsigned32  sec_rgy_bad_nameservice_name    = 0x171220a3;
const unsigned32  sec_rgy_log_entry_out_of_range  = 0x171220a4;
const unsigned32  sec_rgy_era_pwd_mgmt_auth_type  = 0x171220a5;
const unsigned32  sec_rgy_passwd_too_short        = 0x171220a6;
const unsigned32  sec_rgy_passwd_non_alpha        = 0x171220a7;
const unsigned32  sec_rgy_passwd_spaces           = 0x171220a8;

Descriptions:

Interface UUID and Version Number for rs_policy

The interface UUID and version number for the rs_policy interface are given by the following:

[ uuid(4C878280-4000-0000-0D00-028714000000), version(1) ] interface rs_policy { /* begin running listing of rs_policy interface */

rs_properties_get_info()

The rs_properties_get_info() operation retrieves (reads) the RS Policy's property information.

[idempotent] void rs_properties_get_info ( [in] handle_t rpc_handle, [out] sec_rgy_properties_t *properties, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The properties parameter indicates the RS Policy's properties.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the RS Policy object.

rs_properties_set_info()

The rs_properties_set_info() operation modifies (writes) the RS Policy's property information.

void rs_properties_set_info ( [in] handle_t rpc_handle, [in] sec_rgy_properties_t *properties, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The properties parameter indicates the RS Policy's properties.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Management Info (m) permission on the RS's Policy object.

rs_policy_get_info()

The rs_policy_get_info() operation retrieves (reads) an organisation's policy information (or that of the cell).

[idempotent] void rs_policy_get_info ( [in] handle_t rpc_handle, [in] sec_rgy_name_t organization, [out] sec_rgy_plcy_t *policy_data, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The organization parameter indicates the organisation whose policy information is to be retrieved; or, if NULL, the RS Policy's policy information is indicated. (If non-NULL, this string is interpreted as a short PGO name, subordinate to the organisation naming domain-see sec_rgy_name_t-Short and Long PGO Names .)

The policy_data parameter indicates the retrieved policy information.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the object specified by the organization parameter.

rs_policy_set_info()

The rs_policy_set_info() modifies (writes) an organisation's policy information (or that of the cell).

void rs_policy_set_info ( [in] handle_t rpc_handle, [in] sec_rgy_name_t organization, [in] sec_rgy_plcy_t *policy_data, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The organization parameter indicates the organisation whose policy information is to be modified; or, if NULL, the RS Policy's policy information is indicated. (If non-NULL, this string is interpreted as a short PGO name, subordinate to the organisation naming domain-see sec_rgy_name_t-Short and Long PGO Names .)

The policy_data parameter indicates the policy information that is to be written.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Management Info (m) permission on the object specified by the organization parameter.

rs_policy_get_effective()

The rs_policy_get_effective() operation returns an organisation's effective policy information; that is, the more restrictive of the organisation's policy information and the cell's policy information.

[idempotent] void rs_policy_get_effective ( [in] handle_t rpc_handle, [in] sec_rgy_name_t organization, [out] sec_rgy_plcy_t *policy_data, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The organization parameter indicates the organisation whose effective policy information is to be retrieved; or, if NULL, the RS Policy's policy information is indicated. (If non-NULL, this string is interpreted as a short PGO name, subordinate to the organisation naming domain-see sec_rgy_name_t-Short and Long PGO Names .)

The policy_data parameter indicates the returned effective policy information.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the object(s) specified by the organization parameter (that is, on both organisation and RS Policy object, or just RS Policy object).

rs_auth_policy_get_info()

The rs_auth_policy_get_info() operation retrieves (reads) an account's authentication policy information (or that of the cell).

[idempotent] void rs_auth_policy_get_info ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *account, [out] sec_rgy_plcy_auth_t *auth_policy, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The account parameter indicates the account whose authentication policy information is to be retrieved; or if all the fields of account are NULL or empty strings the RS Policy's authentication policy information is indicated.

The auth_policy parameter indicates the retrieved policy information.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the object specified by the account parameter.

rs_auth_policy_get_effective()

The rs_auth_policy_get_effective() operation returns an account's effective authentication policy information; that is, for each sec_rgy_plcy_auth_t field the more restrictive of the account's authentication policy information and the cell's authentication policy information.

[idempotent] void rs_auth_policy_get_effective ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *account, [out] sec_rgy_plcy_auth_t *auth_policy, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The account parameter indicates the account whose effective authentication policy information is to be retrieved; or if all the fields of account are NULL or empty strings the RS Policy's authentication policy information is indicated.

The auth_policy parameter indicates the retrieved policy information.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the object(s) specified by the account parameter (that is, on both account and RS Policy object, or just RS Policy object).

rs_auth_policy_set_info()

The rs_auth_policy_set_info() operation modifies (writes) an account's authentication policy information (or that of the cell).

void rs_auth_policy_set_info ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *account, [in] sec_rgy_plcy_auth_t *auth_policy, [out] rs_cache_data_t *cache_info, [out] error_status_t *status ); } /* end running listing of rs_policy interface */

The rpc_handle parameter identifies the RS server.

The account parameter indicates the account whose authentication policy information is to be modified; or if all the fields of account are NULL or empty strings the RS Policy's authentication policy information is indicated.

The auth_policy parameter indicates the policy information that is to be written.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Authentication Info (a) permission on the object specified by the account parameter.

The rs_pgo RPC Interface

This section specifies (in IDL/NDR) the RS's rs_pgo RPC interface.

Common Data Types and Constants for rs_pgo

The following are common data types and constants used in the rs_pgo interface.

sec_rgy_domain_t

The sec_rgy_domain_t data type represents the RS datastore's PGO domains. For naming purposes (see sec_rgy_name_t-Short and Long PGO Names ), these domains also have stringnames associated with them (and therefore they are also known as naming domains).

typedef signed32 sec_rgy_domain_t; const signed32 sec_rgy_domain_person = 0; const signed32 sec_rgy_domain_group = 1; const signed32 sec_rgy_domain_org = 2;

The following values are currently registered:

Note that three PGO domains are identified in the rs_pgo interface described in this section via the indicated sec_rgy_domain_t values, not via the indicated stringnames. These stringnames occur only in fully-qualified global names, as used by the rdacl RPC interface and sec_acl API (see ACL Editor RPC Interface and Access Control List API ).

sec_rgy_member_t

The sec_rgy_member_t data type represents names in the RS-supported namespace.

typedef char sec_rgy_member_t[sec_rgy_name_t_size];
Note:
There is no substantive difference between the data types sec_rgy_name_t (see sec_rgy_name_t-Short and Long PGO Names ) and sec_rgy_member_t. The existence of the two types is best thought of as being historical.
sec_rgy_pgo_flags_t

The sec_rgy_pgo_flags_t data type represents a flag word of attributes on PGO items.

typedef bitset sec_rgy_pgo_flags_t; const unsigned32 sec_rgy_pgo_is_an_alias = 0x1; const unsigned32 sec_rgy_pgo_is_required = 0x2; const unsigned32 sec_rgy_pgo_projlist_ok = 0x4;

The following values are currently registered:

sec_rgy_pgo_item_t

The sec_rgy_pgo_item_t data type represents the RS datastore information associated with PGO items.

typedef struct { uuid_t id; signed32 unix_num; signed32 quota; sec_rgy_pgo_flags_t flags; sec_rgy_pname_t fullname; } sec_rgy_pgo_item_t;

Its fields are the following:

rs_pgo_id_key_t

The rs_pgo_id_key_t data type represents the data necessary for a lookup-by-UUID query in the RS datastore.

typedef struct { uuid_t id; sec_rgy_name_t scope; } rs_pgo_id_key_t;

Its fields are the following:

rs_pgo_unix_num_key_t

The rs_pgo_unix_num_key_t data type represents the data necessary for a lookup-by-local-ID query in the RS datastore.

typedef struct { signed32 unix_num; sec_rgy_name_t scope; } rs_pgo_unix_num_key_t;

Its fields are the following:

rs_pgo_query_t

The rs_pgo_query_t data type indicates the type of an RS datastore query key (see rs_pgo_query_key_t, rs_pgo_query_key_t ).

typedef enum { rs_pgo_query_name, /* 0 */ rs_pgo_query_id, /* 1 */ rs_pgo_query_unix_num, /* 2 */ rs_pgo_query_next, /* 3 */ rs_pgo_query_none /* 4 */ } rs_pgo_query_t;

The following values are currently registered:

rs_pgo_query_key_t

The rs_pgo_query_key_t data type represents an RS datastore query (lookup) key.

typedef union switch (rs_pgo_query_t query) tagged_union { case rs_pgo_query_name: sec_rgy_name_t name; case rs_pgo_query_id: rs_pgo_id_key_t id_key; case rs_pgo_query_unix_num: rs_pgo_unix_num_key_t unix_num_key; case rs_pgo_query_next: sec_rgy_name_t scope; default: /*empty*/ /*empty*/; } rs_pgo_query_key_t;

Note that the rs_pgo_query_none value of the query discriminator matches the default arm of the union switch.

rs_pgo_result_t

The rs_pgo_result_t data type represents the result of an RS datastore query (lookup).

typedef struct { sec_rgy_name_t name; sec_rgy_pgo_item_t item; } rs_pgo_result_t;

Its fields are the following:

rs_pgo_query_result_t

The rs_pgo_query_result_t data type represents a performance-optimised version of the rs_pgo_result_t data type. In the success case (status = error_status_ok), rs_pgo_query_result_t represents a value of type rs_pgo_result_t); in the error case (status != error_status_ok) it is empty (thereby preventing unnecessary marshalling/unmarshalling of data in the error case).

typedef union switch (signed32 status) tagged_union { case error_status_ok: rs_pgo_result_t result; default: /*empty*/ /*empty*/; } rs_pgo_query_result_t;

Interface UUID and Version Number for rs_pgo

The interface UUID and version number for the rs_pgo interface are given by the following:

[ uuid(4c878280-3000-0000-0d00-028714000000), version(1.0) ] interface rs_pgo { /* begin running listing of rs_pgo interface */

rs_pgo_add()

The rs_pgo_add() operation creates (adds) to the RS's datastore a PGO item that does not currently exist.

void rs_pgo_add ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t pgo_name, [in] sec_rgy_pgo_item_t *pgo_item, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain in which the new item is to be created.

The pgo_name parameter identifies the (name of the) PGO item, subordinate to name_domain, that is to be created. Only terminal objects (that is, PGO items per se) are valid named items in this context-not intermediate directories (between the root of name_domain and the named PGO item), which are created automatically by this operation if necessary (namely, if they do not already exist), and cannot be created directly.

The pgo_item parameter indicates the information that is to be stored in the RS's datastore for the newly created PGO item. The fields of pgo_item indicate the following:

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Insert (i) permission on the parent container of the created PGO item (that is, the container in which the PGO item is to be created).

rs_pgo_delete()

The rs_pgo_delete() operation deletes from the RS's datastore an existing PGO item, together with all accounts depending on that PGO item (that is, having that PGO item as an element).

void rs_pgo_delete ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t pgo_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain from which the PGO item is to be deleted.

The pgo_name parameter identifies the PGO item, subordinate to name_domain, to be deleted. Only terminal objects (that is, PGO items per se) are valid named items in this context- not intermediate directories (between the root of name_domain and the named item), which are deleted automatically by this operation if necessary (namely, if this operation deletes the last entry subordinate to them), and cannot be deleted directly.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Delete Item (D) permission on the PGO item to be deleted, and Delete (d) permission on the parent container of that PGO item.

rs_pgo_replace()

The rs_pgo_replace() operation modifies (writes) an existing PGO item in the RS's datastore.

void rs_pgo_replace ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t pgo_name, [in] sec_rgy_pgo_item_t *pgo_item, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain of the PGO item which is to be modified.

The pgo_name parameter identifies the PGO item, subordinate to name_domain, to be modified.

The pgo_item parameter indicates the new information that is to be written in the RS's datastore for the indicated PGO item. The fields of pgo_item that are generally modifiable are: quota, flags, and fullname. In general, the id field (and hence the unix_num field) cannot be modified by rs_pgo_replace() (such an effect could be achieved through a combination of rs_pgo_delete() and rs_pgo_add(), but it is inadvisable). (This lack of modifiability of the UUID is the sense in which the UUID is the definitive identifier of the PGO item.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: If quota or flags or unix_num is being changed, this operation succeeds only if the calling client has Management Info (m) permission on the PGO item. If fullname is being changed, this operation succeeds only if the calling client has Fullname (f) permission on the PGO item.

rs_pgo_rename()

The rs_pgo_rename() operation modifies the name of a PGO item in the RS's datastore. This operation can modify any portion of a PGO item's name (either its leaf portion, or move the PGO item from one container to another), but it is limited to operate within a single PGO domain.

void rs_pgo_rename ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t old_name, [in] sec_rgy_name_t new_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain of the PGO item which is to be renamed.

The old_name parameter identifies the PGO item, subordinate to name_domain, whose name is to be modified.

The new_name parameter indicates the new name of the PGO item whose name is being modified.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Name (n) permission on the PGO item. If only the last component of the PGO item's name is being changed, the calling client requires no other permissions. If the PGO item is being moved from one container to another (that is, if some part of the PGO item's name other than just its last component is being changed), this operation succeeds only if the calling client has in addition Delete (d) permission on the parent container of old_name, and Insert (i) permission on the parent container of new_name.

rs_pgo_get()

The rs_pgo_get() operation searches for and retrieves (reads) data from an RS server/datastore. This operation returns the datastore information of the next PGO item (with respect to the RS server/datastore's implementation-dependent ordering of PGO items) at or following a specified cursor position, whose stored data matches that indicated by a specified query (lookup) key (where the notion of matching is query-key-specific, as defined below in this section).

[idempotent] void rs_pgo_get ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] rs_pgo_query_key_t *key, [in] boolean32 allow_aliases, [in, out] sec_rgy_cursor_t *item_cursor, [out] rs_cache_data_t *cache_info, [out] rs_pgo_query_result_t *result );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain to be searched. (Searches are limited to a single domain per call.)

The key parameter identifies the query (or lookup) key on which the search is to be based. Namely, the query discriminator of key (see rs_pgo_query_key_t ) takes one of the following values:

The allow_aliases parameter, if non-0 (TRUE), indicates that an alias PGO item matching key satisfies the query request. If 0 (FALSE), only a distinguished (that is, non-alias) PGO item can satisfy the query request.

On input, the item_cursor parameter indicates the current cursor position (so that the PGO item it indicates is eligible to be matched, as are all the items following it); on output it indicates the cursor position next following the retrieved PGO item. The item_cursor does not automatically wrap around from the end of the datastore to its beginning: instead, the sec_rgy_no_more_entries status value is returned in the result parameter if the requested item is not matched between the current cursor position and the end of the datastore (and item_cursor remains indicating the end of the datastore in this case).

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The result parameter returns the retrieved information for the matched PGO item.

The status of this operation is indicated by the result element of the result parameter.

The ritual for using rs_pgo_get() is as follows. Before making the first rs_pgo_get() call, the item_cursor parameter must be initialised to the beginning of the RS's datastore (modulo any scoping information), by setting the *item_cursor.valid field to 0 (FALSE); the other fields of *item_cursor may be set to any convenient value. In the returned value of item_cursor, the RS server will set values that it (and only it) can interpret. The client uses this returned value of item_cursor, without modifying it, for a subsequent call. This ritual may be followed for a sequence of successive calls, until the end of the datastore is reached (that is, sec_rgy_no_more_entries status value is returned). In any such sequence of calls, the same name_domain and key parameters must be used (otherwise, the results are undefined).

Required rights: This operation succeeds only if the calling client has Read (r) permission on the matched PGO item.

rs_pgo_key_transfer()

The rs_pgo_key_transfer() operation converts one of an RS datastore item's query keys (PGO item's name, UUID or local-ID) into another. Using this operation may be more efficient and/or convenient than using rs_pgo_get() when one query key is known, another is desired, and other datastore information is not needed. In other words, this operation implements the six mappings: name->UUID, UUID->name, name->local-ID, local-ID->name, UUID->local-ID, and local-ID->UUID.

[idempotent] void rs_pgo_key_transfer ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] rs_pgo_query_t requested_result_type, [in, out] rs_pgo_query_key_t *key, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter identifies the PGO domain to be searched.

The requested_result_type parameter indicates the query key to which key is to be converted.

On input, the key parameter indicates a query key which is to be converted. On output, it indicates the converted query key.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: In the cases where no name query key is involved (that is, the UUID->local-ID and local-ID->UUID cases), this operation succeeds unconditionally. In the cases where a name query key is involved (that is, the name->UUID, UUID->name, name->local-ID and local-ID->name cases), this operation succeeds only if the calling client has at least some (any) access permission to the PGO item.

rs_pgo_add_member()

The rs_pgo_add_member() operation adds a member principal to the membership list of a group or organisation.

void rs_pgo_add_member ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t go_name, [in] sec_rgy_name_t person_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter indicates the domain of interest (it must be sec_rgy_domain_group or sec_rgy_domain_org; it may not be sec_rgy_domain_person).

The go_name parameter indicates the group or organisation item, subordinate to name_domain, to which the member is to be added.

The person_name parameter indicates the principal item to be added to the go_name item.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Membership (M) permission on the item indicated by go_name. If further go_name is a group (as opposed to an organisation), then the calling client must also have Group (g) permission on the principal indicated by person_name.

rs_pgo_delete_member()

The rs_pgo_delete_member() operation deletes a member principal from the membership list of a group or organisation, together with all accounts depending on that member (that is, having the specified principal, and group or organisation).

void rs_pgo_delete_member ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t go_name, [in] sec_rgy_name_t person_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter indicates the domain of interest (it must be sec_rgy_domain_group or sec_rgy_domain_org; it may not be sec_rgy_domain_person).

The go_name parameter indicates the group or organisation item, subordinate to name_domain, from which the member is to be deleted.

The person_name parameter indicates the principal item to be deleted from the go_name item.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Membership (M) permission on the item indicated by go_name.

rs_pgo_is_member()

The rs_pgo_is_member() operation determines whether a principal is a member of a group or organisation.

[idempotent] boolean32 rs_pgo_is_member ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t go_name, [in] sec_rgy_name_t person_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The name_domain parameter indicates the domain of interest (it must be sec_rgy_domain_group or sec_rgy_domain_org; it may not be sec_rgy_domain_person).

The go_name parameter indicates the name of the group or organisation item, subordinate to name_domain, for which membership is being queried.

The person_name parameter indicates the principal item whose membership in the go_name item is being queried.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

The boolean32 return value returns non-0 (TRUE) if person_name is a member of go_name, and 0 (FALSE) otherwise.

Required rights: This operation succeeds only if the calling client has Test (t) permission on the item indicated by go_name.

rs_pgo_get_members()

The rs_pgo_get_members() operation retrieves the list of member principals of a group or organisation, or the list of groups to which a principal belongs.

[idempotent] void rs_pgo_get_members ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t name_domain, [in] sec_rgy_name_t go_name, [in, out] sec_rgy_cursor_t *member_cursor, [in] signed32 max_members, [out, length_is(*number_supplied), size_is(max_members)] sec_rgy_member_t member_list[], [out] signed32 *number_supplied, [out] signed32 *number_members, [out] rs_cache_data_t *cache_info, [out] error_status_t *status ); } /* end running listing of rs_pgo interface */

The rpc_handle parameter identifies the RS server.

The name_domain parameter indicates the PGO domain of interest. If name_domain is sec_rgy_domain_group or sec_rgy_domain_org, the principals which are members of the group or organisation indicated by go_name are to be returned in member_list[]. If name_domain is sec_rgy_domain_person, the groups of which the principal indicated by go_name is a member are to be returned in member_list[].

The go_name parameter indicates the PGO item, subordinate to name_domain, whose membership is being queried.

The member_cursor parameter indicates, on input, the current cursor position (so that the items at and following this position are eligible to be retrieved on the current invocation of this operation); on output, it indicates the cursor position next following the retrieved item(s).

The max_members parameter indicates the maximum number of members to be retrieved in member_list[].

The member_list parameter indicates the retrieved members.

The number_supplied parameter indicates the actual number of retrieved members.

The number_members parameter indicates the total number of members available for the go_name item. (The member_cursor parameter is used to coordinate multiple invocations to retrieve the complete list of members.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the go_name item.

The rs_acct RPC Interface

This section specifies (in IDL/NDR) the RS's rs_acct RPC interface.

Common Data Types and Constants for rs_acct

The following are common data types and constants used in the rs_acct interface.

sec_rgy_acct_key_t

The sec_rgy_acct_key_t data type indicates the minimal portion of an account's <P, G, O> name triple that is required to unambiguously identify the account-that is, the minimal name information (or abbreviation) that constitutes an RS datastore query key for the account.

typedef signed32 sec_rgy_acct_key_t; const signed32 sec_rgy_acct_key_person = 1; const signed32 sec_rgy_acct_key_group = 2; const signed32 sec_rgy_acct_key_org = 3;

The following values are currently registered:

sec_rgy_acct_admin_flags_t

The sec_rgy_acct_admin_flags_t data type is a flag word representing administrative flags.

typedef bitset sec_rgy_acct_admin_flags_t; const unsigned32 sec_rgy_acct_admin_valid = 0x1; const unsigned32 sec_rgy_acct_admin_server = 0x4; const unsigned32 sec_rgy_acct_admin_client = 0x8;

The following values are currently registered:

sec_rgy_acct_auth_flags_t

The sec_rgy_acct_auth_flags_t data type is a flag word representing account authentication flags.

typedef bitset sec_rgy_acct_auth_flags_t; const unsigned32 sec_rgy_acct_auth_tgt = 0x4;

The following values are currently registered:

sec_rgy_foreign_id_t

The sec_rgy_foreign_id_t data type represents identities (principals, groups and organisations, despite the field name principal in the defining structure below) from arbitrary cells (including the local interpreting cell; that is, not necessarily a strictly foreign non-local cell). This data type is defined as follows (compare to the sec_id_foreign_t data type, Local and Foreign Authorisation Identities ):

typedef struct sec_rgy_foreign_id_t { uuid_t principal; uuid_t cell; } sec_rgy_foreign_id_t;

Its fields are the following:

sec_rgy_acct_admin_t

The sec_rgy_acct_admin_t data type represents administration-level information about accounts held in the RS datastore.

typedef struct { sec_rgy_foreign_id_t creator; sec_timeval_sec_t creation_date; sec_rgy_foreign_id_t last_changer; sec_timeval_sec_t change_date; sec_timeval_sec_t expiration_date; sec_timeval_sec_t good_since_date; sec_rgy_acct_admin_flags_t flags; sec_rgy_acct_auth_flags_t authentication_flags; } sec_rgy_acct_admin_t;

Its fields are the following:

sec_rgy_acct_user_flags_t

The sec_rgy_acct_user_flags_t data type represents a flag word of attributes about users.

typedef bitset sec_rgy_acct_user_flags_t; const unsigned32 sec_rgy_acct_user_passwd_valid = 0x1;

The following values are currently registered:

sec_passwd_type_t

The sec_passwd_type_t data type represents password type (either a true password to be mapped to a cryptographic key, or else a cryptographic key; for usage, see sec_passwd_rec_t ).

typedef enum { sec_passwd_none, /* 0 */ sec_passwd_plain, /* 1 */ sec_passwd_des /* 2 */ } sec_passwd_type_t;

The following values are currently registered:

sec_key_version_t

The sec_key_version_t data type indicates the version number of a long-term cryptographic key associated to an account held in the RS datastore. It is used in identifying the version number of uninterpreted byte strings of encrypted network data. See sec_encrypted_bytes_t for its usage.

typedef unsigned32 sec_key_version_t;
sec_passwd_version_t

The sec_passwd_version_t data type indicates the version number of a long-term cryptographic key (and hence, by extension, its associated password, if there is one) associated to an account held in the RS datastore.

typedef unsigned32 sec_passwd_version_t; const unsigned32 sec_c_key_version_none = 0; const unsigned32 sec_passwd_c_version_none = 0;

Key version numbers have the following semantics. Every account has zero or more keys associated with it; every valid account has exactly one key associated with it, with the potential (notable) exceptions of the RS (dce-rgy), PS (dce-ptgt) and KDS (or cell, krbtgt/cell-name) principals in every cell. (Typically, implementations will support multiple simultaneous keys for these principals, so that their keys can be updated regularly without invalidating the many unexpired (ticket-granting) tickets that have been issued (protected) under previous keys; when such an update occurs, the old key is retained until the account's maximum renewable ticket lifetime is reached (see sec_rgy_plcy_auth_t ), at which time it can be discarded.) Every such key has one and only one version number attached to it (a value of type sec_passwd_version_t). All the keys associated with a given account must all be distinct, and must all have different key version numbers attached to them. No key may ever have the version number sec_c_key_version_none. These key version numbers are used to distinguish among the various keys associated with an account, as follows.

Under normal circumstances (that is, in the stable operating configuration), an account has exactly one key associated with it. But due to security considerations (namely, the longer a key has been used, and the greater the volume of traffic it has encrypted, the more susceptible it is to compromise), the value of this key needs to be changed from time to time. (For a human user, this is manifested as changing the user's password; for a non-human server, it is manifested as changing the server's key.) However, when a new key is associated with an account, the old key needs to be retained until it times out; that is, until all the tickets that could legitimately be protected by the old key have expired. Thus, KDSs must always use accounts' most recent keys to protect all tickets. Finally, all KDSs must implement the successive versions of keys by means of strictly increasing version numbers (typically, incrementing by 1 for each new version number), and the most recent key must always be that having the highest version number (no provision is specified here for overflow of the sec_passwd_version_t data type-note, however, that keys are typically changed at most once an hour, and that 232 hours ~ 490,000 years, so the likelihood of colliding key version numbers is insignificant).

Note:
The condition given here (namely, that the most recent key must correspond to the highest version number, and the related restriction to strictly increasing version numbers) might reasonably be expected to be implementation details, as opposed to specification requirements. Nevertheless, the description as given here is consistent with the Kerberos specification. [RFC 1510: 4.1]


The following values are currently registered:

sec_passwd_des_key_t

The sec_passwd_des_key_t data type represents a (64-bit) DES key.

const unsigned32 sec_passwd_c_des_key_size = 8; typedef byte sec_passwd_des_key_t[sec_passwd_c_des_key_size];

The mapping of bit-vectors to byte-vectors is the usual one (see Bits, Bytes, Words, and so on ), namely: if K = <k0, ···, k63> is a 64-bit DES key, then it is represented as the 8-byte sec_passwd_des_key_t vector <<k0, ···, k7>, ···, <k56, ···, k63>>.

sec_passwd_rec_t

The sec_passwd_rec_t data type represents a password or cryptographic key record.

typedef struct { sec_passwd_version_t version_number; [string, ptr] char *pepper; union switch (sec_passwd_type_t key_type) { case sec_passwd_plain: [string, ptr] char *plain; case sec_passwd_des: sec_passwd_des_key_t des_key; } key; } sec_passwd_rec_t;

Its fields are the following:

For a description of how this data type is used, see rs_acct_key_transmit_t .

sec_chksum_type_t

The sec_chksum_type_t data type represents checksum type.

typedef enum { sec_chksum_none, /* 0 */ sec_chksum_crc32, /* 1 */ sec_chksum_des_cbc, /* 2 */ sec_chksum_rsa_md4, /* 3 */ sec_chksum_rsa_md4_des /* 4 */ } sec_chksum_type_t;

The following values are currently registered:

sec_chksum_t

The sec_chksum_t data type represents a checksum.

typedef struct { sec_chksum_type_t chksum_type; unsigned32 len; [size_is(len), ptr] byte *chksum; } sec_chksum_t;

Its fields are the following:

For a description of how this data type is used, see rs_acct_key_transmit_t .

sec_rgy_unix_passwd_buf_t

The sec_rgy_unix_passwd_t data type represents a (protected) (local) password (as opposed to a long-term key); that is, one whose exact interpretation (for example, the manner of its protection, or its usage by local operating systems) is implementation-specific (and whose further specification is therefore beyond the scope of DCE). (The use of the substring unix in the name of this data type is historical.) (Protected passwords are sometimes said to be encrypted, but this is usually a misnomer because passwords are usually protected by non-invertible cryptographic checksum techniques, not by invertible encryption/decryption techniques.)

const unsigned32 sec_rgy_max_unix_passwd_len = 16; typedef [string] char sec_rgy_unix_passwd_buf_t[sec_rgy_max_unix_passwd_len];
sec_rgy_acct_user_t

The sec_rgy_acct_user_t data type represents user-level information about accounts held in the RS datastore.

typedef struct { sec_rgy_pname_t gecos; sec_rgy_pname_t homedir; sec_rgy_pname_t shell; sec_passwd_version_t passwd_version_number; sec_timeval_sec_t passwd_dtm; sec_rgy_acct_user_flags_t flags; sec_rgy_unix_passwd_buf_t passwd; } sec_rgy_acct_user_t;

Its fields are the following:

rs_acct_parts_t

The rs_acct_parts_t data type is a flag word used to indicate portions of an account's datastore information. In the current revision of DCE, the only place this is used is in conjunction with the rs_acct_replace() operation (see rs_acct_replace() ), where it indicates what parts of the account's information are being updated by a given invocation of rs_acct_replace(). (This allows, for example, multiple partial APIs (unspecified in this revision of DCE) to be layered over the single complete RPC rs_acct_replace() operation.)

typedef bitset rs_acct_parts_t; const unsigned32 rs_acct_part_user = 0x1; const unsigned32 rs_acct_part_admin = 0x2; const unsigned32 rs_acct_part_passwd = 0x4; const unsigned32 rs_acct_part_login_name = 0x10;

The following values are currently registered (see rs_acct_replace() for details):

rs_encrypted_pickle_t

The rs_encrypted_pickle_t data type represents a cryptographically encrypted pickle (see (IDL/NDR) Pickles for the definition of pickles). (The encryption type and key are not specified here, but must be specified by other means in any application of this data type.)

typedef struct { unsigned32 enc_pickle_len; [ref, size_is(enc_pickle_len)] byte *enc_pickle; } rs_encrypted_pickle_t;

Its fields are the following:

sec_etype_t

The sec_etype_t data type indicates encryption type.

typedef enum { sec_etype_none, /* 0 */ sec_etype_des_cbc_crc /* 1 */ } sec_etype_t;

The following values are currently registered:

sec_bytes_t

The sec_bytes_t data type represents a generic pickle type for uninterpreted byte strings of network data.

typedef struct {
    unsigned32                        num_bytes;
    [size_is(num_bytes), ptr] byte    *bytes;
} sec_bytes_t;

Its fields are the following:

sec_encrypted_bytes_t

The sec_encrypted_bytes_t data type represents a generic pickle type for encrypting byte strings of network data.

typedef struct  {
    sec_etype_t              etype;
    sec_key_version_t        ekvno;
    sec_bytes_t              ebytes;
} sec_encrypted_bytes_t;

Its fields are the following:

rs_acct_key_transmit_t

The rs_acct_key_transmit_t data type represents cryptographic keying information (cryptographic key or DES key), protected for transmittal in communications.

typedef struct { sec_etype_t enc_type; sec_passwd_type_t enc_keytype; sec_passwd_version_t enc_key_version; unsigned32 key_pickle_len; [ref] rs_encrypted_pickle_t *key; [ref] rs_encrypted_pickle_t *checksum; } rs_acct_key_transmit_t;

Its fields are the following (for further elucidation of all these fields and how they are used, see below):

This data type is used (in rs_acct_add() and rs_acct_replace()) as follows.

A principal (acting as an RS RPC client) stores keying information (password or cryptographic key) in a sec_passwd_rec_t record (see sec_passwd_rec_t ), and pickles this sec_passwd_rec_t. The principal then encrypts the sec_passwd_rec_t pickle (using sec_chksum_none when enc_type sec_etype_none, and using sec_chksum_des_cbc when enc_type = sec_etype_des_cbc_crc-see sec_chksum_type_t and sec_chksum_t ) in its (the principal's) own long-term key-this encrypted pickle is the key field. The principal also computes the checksum over the (unencrypted) sec_passwd_rec_t pickle (using cksumType-TRIVIAL when enc_type = sec_etype_none, and using DES-CBC-CKSUM with initialisation vector 0 when enc_type = sec_etype_des_cbc_crc-see DES-CBC Checksum and Registered Checksum Types ), stores that in a sec_chksum_t data type, pickles it, and encrypts that pickle in its long-term key-this encrypted pickle is the checksum field. The client stores the encrypting information used for these encryptions (that is, information about its own long-term key) in the enc_type, enc_keytype, enc_key_version and in key_pickle_len fields.

On the receiving end, the RS server retrieves the client principal's (authenticated) identity from the protected RPC runtime (see Protected RPC ), retrieves the client's long-term key using this identity and the enc_type, enc_keytype, enc_key_version fields of the rs_acct_key_transmit_t, then uses this information and key_pickle_len to decrypt key and checksum, thereby retrieving the sec_passwd_rec_t and sec_chksum_t pickles, and thence the original transmitted keying data.

sec_rgy_sid_t

The sec_rgy_sid_t data type represents an account's UUIDs.

typedef struct sec_rgy_sid_t { uuid_t person; uuid_t group; uuid_t org; } sec_rgy_sid_t;

Its fields are the following:

sec_rgy_unix_sid_t

The sec_rgy_unix_sid_t data type represents an account's local-IDs.

typedef struct { signed32 person; signed32 group; signed32 org; } sec_rgy_unix_sid_t;

Its fields are the following:

rs_acct_info_t

The rs_acct_info_t data type represents a performance-optimised data type for returning account data. In the success case (status = error_status_ok), rs_acct_info_t represents a value of type struct result (see definition below); in the error case (status != error_status_ok) it is empty (thereby preventing unnecessary marshalling/unmarshalling of data in the error case).

typedef union switch (signed32 status) { case error_status_ok: struct { sec_rgy_acct_key_t key_parts; sec_rgy_sid_t sid; sec_rgy_unix_sid_t unix_sid; sec_rgy_acct_admin_t admin_part; sec_rgy_acct_user_t user_part; } result; default: /*empty*/ /*empty*/; } rs_acct_info_t;

The fields of result are the following:

Interface UUID and Version Number for rs_acct

The interface UUID and version number for the rs_acct interface are given by the following:

[ uuid(4c878280-2000-0000-0d00-028714000000), version(1.0) ] interface rs_acct { /* begin running listing of rs_acct interface */

rs_acct_add()

The rs_acct_add() operation adds (or registers) an account to the RS datastore.

void rs_acct_add ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in, out] sec_rgy_acct_key_t *key_parts, [in] sec_rgy_acct_user_t *user_part, [in] sec_rgy_acct_admin_t *admin_part, [in, ref] rs_acct_key_transmit_t *key, [in] sec_passwd_type_t new_keytype, [out] sec_passwd_version_t *new_key_version, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account to be registered (added).

The key_parts parameter indicates the minimal portion of login_name's <P, G, O> name triple that is required to identify the account.

The user_part parameter indicates the user-level portion of the account's datastore data.

The admin_part parameter indicates the administrative-level portion of the account's datastore data.

The key parameter indicates the long-term cryptographic key to be stored in the RS's datastore for this account. Namely, if key carries a cryptographic key, that is stored as the account's long-term key; if key carries a password (and possibly also pepper), then that is transformed into a cryptographic key according to the type specified by the new_keytype parameter (see Registered Password-to-Key Mappings ), and that is stored as the account's long-term key.

The new_keytype parameter indicates the type of the long-term cryptographic key determined by key. (If key carries a cryptographic key instead of a password, then the type of that key must be the same as key.)

The new_key_version parameter indicates the version number of the long-term cryptographic key determined by key. This version number may be specified by the client (in the version_number field of the sec_passwd_rec_t structure of key). If the client specifies sec_c_key_version_none, then the server assigns it. In either case, the version number is returned to the client in new_key_version. (In the sec_c_key_version_none case, the server typically assigns the next smallest available version number; that is, 1 in the case of a new account, incrementing the old version number by 1 in the case of a pre-existing account.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has the following permissions on the principal component of the account to be added ((*login_name).pname): Management Info (m), Authentication Info (a) and User Info (u).

rs_acct_delete()

The rs_acct_delete() operation deletes (removes) an account from the RS datastore.

void rs_acct_delete ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account to be deleted.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has the following permissions on the principal component of the account to be deleted ((*login_name).pname): Management Info (m), Authentication Info (a) and User Info (u).

rs_acct_rename()

The rs_acct_rename() operation renames an account; that is, it associates a different <P, G, O> name triple to an existing account's data in the RS datastore, but with the restriction that the principal component cannot be changed.

void rs_acct_rename ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *old_login_name, [in] sec_rgy_login_name_t *new_login_name, [in, out] sec_rgy_acct_key_t *new_key_parts, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The old_login_name parameter identifies the existing name associated with the account data.

The new_login_name parameter identifies the new name to be associated with the account data. The new principal component ((*new_login_name).pname) must be the same as the old principal component ((*old_login_name).pname).

The new_key_parts parameter indicates the minimal portion of new_login_name's <P, G, O> name triple that is required to identify the account.

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Management Info (m) permission on the principal component of the existing account ((*old_login_name).pname).

rs_acct_lookup()

The rs_acct_lookup() operation retrieves (reads) account data from the RS server/datastore. This operation returns the datastore information of the next account, at or following a specified cursor position, whose name matches that indicated by a specified account <P, G, O> name triple (where the notion of matching recognises wildcards).

[idempotent] void rs_acct_lookup ( [in] handle_t rpc_handle, [in, out] sec_rgy_login_name_t *login_name, [in, out] sec_rgy_cursor_t *cursor, [out] rs_cache_data_t *cache_info, [out] rs_acct_info_t *result );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account to be read from. On input, any of its components ((*login_name).pname, (*login_name).gname or (*login_name).oname) which is empty (that is, of length 0) is considered to be a wildcard (that is, not used as a matching criterion-every name matches an empty string). On output, all components of login_name are non-empty, and indicate the account whose data is retrieved in result.

The cursor parameter indicates, on input, the current cursor position (so that the accounts at and following this position are eligible to be retrieved on the current invocation of this operation). On output, the cursor parameter indicates the cursor position next following the retrieved account(s). (See sec_rgy_cursor_t .)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The result parameter represents the result of this operation.

The status of this operation is indicated by the status of the result parameter.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the principal component of the matched account ((*login_name).pname).

rs_acct_replace()

The rs_acct_replace() operation modifies (writes) account data in the RS server/datastore.

void rs_acct_replace ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in, out] sec_rgy_acct_key_t *key_parts, [in] rs_acct_parts_t modify_parts, [in] sec_rgy_acct_user_t *user_part, [in] sec_rgy_acct_admin_t *admin_part, [in, ptr] rs_acct_key_transmit_t *key, [in] sec_passwd_type_t new_keytype, [out] sec_passwd_version_t *new_key_version, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account to be replaced (modified, written, updated).

The key_parts parameter indicates the minimal portion of the login_name's <P, G, O> name triple that is required to identify the account. (Even though key_parts is specified as both an input and output parameter, it is used only as an input parameter for this operation.)

The modify_parts parameter indicates which portion(s) of the account's datastore information is to be updated:

The user_part parameter indicates new user-level information.

The admin_part parameter indicates new administrative-level information.

The key parameter indicates a new long-term cryptographic key. (See the description of the key parameter of rs_acct_add().)

The new_keytype parameter indicates the type of the long-term cryptographic key determined by key. (See the description of the new_keytype parameter of rs_acct_add().)

The new_key_version parameter indicates the version number or number of the long-term cryptographic key determined by key. (See the description of the new_key_version parameter of rs_acct_add().)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has the following permission(s) on the principal component of the account to be modified ((*login_name).pname):

rs_acct_get_projlist()

The rs_acct_get_projlist() operation retrieves an account's project list; that is, the primary group and the concurrent secondary group list associated with the principal component of the account ((*login_name).pname).

[idempotent] void rs_acct_get_projlist ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in, out] sec_rgy_cursor_t *projlist_cursor, [in] signed32 max_number, [out] signed32 *supplied_number, [out, length_is(*supplied_number),size_is(max_number)] uuid_t id_projlist[], [out, length_is(*supplied_number),size_is(max_number)] signed32 unix_projlist[], [out] signed32 *num_projects, [out] rs_cache_data_t *cache_info, [out] error_status_t *status ); } /* end running listing of rs_acct interface */

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account whose project list is to be retrieved.

The projlist_cursor parameter indicates, on input, the current cursor position (so that the concurrent groups at and following this position are eligible to be retrieved on the current invocation of this operation). On output, projlist_cursor indicates the cursor position next following the retrieved concurrent group(s). (See sec_rgy_cursor_t .)

The max_number parameter indicates the maximum number of concurrent groups to be retrieved.

The supplied_number parameter indicates the number of retrieved concurrent groups.

The id_projlist parameter indicates the UUIDs of retrieved concurrent groups.

The unix_projlist parameter indicates the local-IDs of retrieved concurrent groups.

The num_projects parameter indicates the total number of concurrent groups associated with the account (that is, with (*login_name).pname). (The projlist_cursor parameter is used to coordinate multiple invocations to retrieve the complete project list of concurrent groups.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

Required rights: This operation succeeds only if the calling client has Read (r) permission on the principal component of the account ((*login_name).pname).

The rs_misc RPC Interface

This section specifies (in IDL/NDR) the RS's rs_misc RPC interface.

Common Data Types and Constants for rs_misc

The following are common data types and constants used in the rs_misc interface.

rs_login_info_t

The rs_login_info_t data type represents account data, appropriate for network and local system login usage. It is performance-optimised (see rs_pgo_query_result_t) so that in the success case (status = error_status_ok), rs_login_info_t represents account data; in the error case (status != error_status_ok) it is empty (thereby preventing unnecessary marshalling/unmarshalling of data in the error case).

typedef union switch (long status) tagged_union { case error_status_ok: struct { sec_rgy_acct_key_t key_parts; sec_rgy_sid_t sid; sec_rgy_unix_sid_t unix_sid; sec_rgy_acct_user_t user_part; sec_rgy_acct_admin_t admin_part; sec_rgy_plcy_t policy_data; sec_rgy_name_t cell_name; uuid_t cell_uuid; } result; default: /*empty*/ /*empty*/; } rs_login_info_t;

The fields of result are the following:

rs_update_seqno_t

The rs_update_seqno_t data type represents an event's monotonically increasing sequence number assigned by the master.

typedef struct { unsigned32 high; unsigned32 low; } rs_update_seqno_t;

Interface UUID and Version Number for rs_misc

The interface UUID and version number for the rs_misc interface are given by the following:

[ uuid(4c878280-5000-0000-0d00-028714000000), version(1.0) ] interface rs_misc { /* begin running listing of rs_misc interface */

rs_login_get_info()

The rs_login_get_info() operation retrieves (reads) account data from the RS server/datastore.

[idempotent] void rs_login_get_info ( [in] handle_t rpc_handle, [in, out] sec_rgy_login_name_t *login_name, [out] rs_cache_data_t *cache_info, [out] rs_login_info_t *result, [in] signed32 max_number, [out] signed32 *supplied_number, [out, length_is(*supplied_number),size_is(max_number)] uuid_t id_projlist[], [out, length_is(*supplied_number),size_is(max_number)] signed32 unix_projlist[], [out] signed32 *num_projects ); }

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the (name of the) account whose information is to be retrieved.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The result parameter represents the bulk of the information returned by this operation.

Note:
The project list information returned by this operation does not occur in the rs_login_info_t data type because the IDL language does not permit conformant arrays in union arms.

The max_number parameter indicates the maximum number of concurrent groups to be retrieved.

The supplied_number parameter indicates the number of retrieved concurrent groups.

The id_projlist parameter indicates the UUIDs of retrieved concurrent groups.

The unix_projlist parameter indicates the local-IDs of retrieved concurrent groups.

The num_projects parameter indicates the total number of concurrent groups associated with the account (that is, with (*login_name).pname).

The status of this operation is indicated by the status of the result parameter.

Required rights: This operation supports name-based authorisation for local principals only (that is, those in the same cell as this RS server), in addition to the usual EPAC-based authorisation supported by other RS RPC operations (that is a special characteristic of this operation). In either case, this operation succeeds only if the calling client has Read (r) permission on the principal component of the account ((*login_name).pname).

This operation provides all of the credentials and login policy information required for both network and local logins. Apart from its characteristic support of name-based authorisation, this operation is a mere optimisation; it duplicates in a single operation the core functionality that is embodied in four other RS operations, namely rs_properties_get_info(), rs_policy_get_info(), rs_acct_lookup() and rs_acct_get_projlist().

rs_wait_until_consistent()

The rs_wait_until_consistent() operation returns a value of TRUE once all replicas have been updated. Otherwise, at least one replica is incommunicado.

boolean32 rs_wait_until_consistent ( [in] handle_t rpc_handle, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_check_consistency()

The rs_check_consistency() operation performs a non-blocking check for replica consistency.

boolean32 rs_check_consistency ( [in] handle_t rpc_handle, [out] boolean32 *retry, [in,out] rs_update_seqno_t *seqno, [out] rs_cache_data_t *cache_info, [out] error_status_t *status ); } /* end running listing of rs_misc interface */

The rpc_handle parameter identifies the RS server.

The retry parameter, if TRUE, indicates that a replica is responsive but not consistent (out of sync).

As input, the seqno parameter is set to NULL by the client. As output, seqno contains the reference sequence number required for subsequent polling attempts to a responsive but inconsistent replica.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

The client calls rs_check_consistency() initially with a NULL seqno. The operation returns a retry value of TRUE and a reference seqno to be used for subsequent polling attempts to any replica that is responsive but inconsistent (out of sync).

This routine returns a value of TRUE if none of the polled replicas are incommunicado.

The rs_attr RPC Interface

This section specifies (in IDL/NDR) the RS's rs_attr RPC interface.

Common Data Types and Constants for rs_attr

The following are common data types and constants used in the rs_attr interface.

sec_attr_component_name_t

The sec_attr_component_name_t data type is a pointer to a character string used to further specify the object to which the attribute is attached. (Note that this data type is analogous to the sec_acl_component_name_t data type in the ACL interface.)

typedef [string, ptr] unsigned char *sec_attr_component_name_t;
rs_attr_cursor_t

The rs_attr_cursor_t data type provides a datastore scan cursor (that is, a position indicator) for iterative database operations for schema and attribute interfaces.

typedef struct { uuid_t source; unsigned32 object; unsigned32 list; unsigned32 entry; unsigned32 num_entries_left; boolean32 valid; } rs_attr_cursor_t;

Its fields are the following:

sec_attr_bind_auth_info_type_t

The sec_attr_bind_auth_info_type_t data type is an enumeration that defines whether or not an RPC binding is authenticated. This data type is used in conjunction with the sec_attr_bind_auth_info_t data type to set up the authorization method and parameters for an RPC binding.

typedef enum { sec_attr_bind_auth_none, sec_attr_bind_auth_dce } sec_attr_bind_auth_info_type_t;

The following values are currently registered:

sec_attr_bind_auth_info_t

The sec_attr_bind_auth_info_t data type is a discriminated union that defines authorization and authentication parameters for an RPC binding. This data type is used in conjunction with the sec_attr_bind_auth_info_type_t data type to set up the authorization method and parameters for an RPC binding.

typedef union switch (sec_attr_bind_auth_info_type_t info_type) tagged_union { case sec_attr_bind_auth_none: ; case sec_attr_bind_auth_dce: struct { [string, ptr] char *svr_princ_name; unsigned32 protect_level; unsigned32 authn_svc; unsigned32 authz_svc; } dce_info; } sec_attr_bind_auth_info_t;

The sec_attr_bind_auth_info_t data type consists of the following elements:

sec_attr_bind_type_t

The sec_attr_bind_type_t data type specifies the binding type for attribute operations.

typedef unsigned32 sec_attr_bind_type_t; const unsigned32 sec_attr_bind_type_string = 0; const unsigned32 sec_attr_bind_type_twrs = 1; const unsigned32 sec_attr_bind_type_svrname = 2;

The following values are currently registered:

sec_attr_twr_ref_t

The sec_attr_twr_ref_t data type represents a pointer to an RPC protocol tower (twr_t, defined in Appendix L, Protocol Tower Encoding, of the referenced Open Group DCE 1.1 RPC Specification).

typedef [ptr] twr_t *sec_attr_twr_ref_t;
sec_attr_twr_set_t

The sec_attr_twr_set_t data type is a structure that defines an array of towers. This data is used by the client to pass an unallocated array of towers, which the server must allocate.

typedef struct { unsigned32 count; [size_is(count)] sec_attr_twr_ref_t towers[]; } sec_attr_twr_set_t; typedef [ptr] sec_attr_twr_set_t *sec_attr_twr_set_p_t;

Its fields are the following:

sec_attr_bind_svrname

The sec_attr_bind_svrname data type specifies the name of the server for lookup in a directory service.

typedef struct { unsigned32 name_syntax; [string, ptr] char *name; } sec_attr_bind_svrname;

This data type contains the following elements:

sec_attr_binding_t

The sec_attr_binding_t data type is the trigger server's binding union.

typedef union switch (sec_attr_bind_type_t bind_type) tagged_union { case sec_attr_bind_type_string: [string, ptr] char *string_binding; case sec_attr_bind_type_twrs: [ptr] sec_attr_twr_set_t *twr_set; case sec_attr_bind_type_svrname: [ptr] sec_attr_bind_svrname *svrname; } sec_attr_binding_t; typedef [ptr] sec_attr_binding_t *sec_attr_binding_p_t;

This data type contains the following elements:

sec_attr_bind_info_t

The sec_attr_bind_info_t data type specifies attribute trigger binding information.

typedef struct { sec_attr_bind_auth_info_t auth_info; unsigned32 num_bindings; [size_is(num_bindings)] sec_attr_binding_t bindings[]; } sec_attr_bind_info_t;
This data type contains the following elements:
sec_attr_enc_printstring_p_t

The sec_attr_enc_printstring_p_t data type is a pointer to a printstring encoding type structure.

typedef [string, ptr] unsigned char *sec_attr_enc_printstring_p_t;
sec_attr_enc_str_array_t

The sec_attr_enc_str_array_t data type defines a printstring array.

typedef struct { unsigned32 num_strings; [size_is(num_strings)] sec_attr_enc_printstring_p_t strings[]; } sec_attr_enc_str_array_t;
This data type contains the following elements:
sec_attr_enc_bytes_t

The sec_attr_enc_bytes_t data type defines the length of attribute encoding values for attributes whose values are defined to be byte strings.

typedef struct { unsigned32 length; [size_is(length)] byte data[]; } sec_attr_enc_bytes_t;

This data type contains the following elements:

sec_attr_i18n_data_t

The sec_attr_i18n_data_t data type defines the codeset and value length of the encoding values of attributes whose values are defined to be internationalized byte strings.

typedef struct { unsigned32 codeset; unsigned32 length; [size_is(length)] byte data[]; } sec_attr_i18n_data_t;

This data type contains the following elements:

sec_attr_enc_attr_set_t

The sec_attr_enc_attr_set_t data type supplies the UUIDs of each member of a set of attributes.

typedef struct { unsigned32 num_members; [size_is(num_members)] uuid_t members[]; } sec_attr_enc_attr_set_t;

This data type contains the following elements:

sec_attr_encoding_t

The sec_attr_encoding_t data type is an enumerator that contains attribute encoding tags used to define the legal encodings for attribute values.

typedef enum { sec_attr_enc_any, sec_attr_enc_void, sec_attr_enc_integer, sec_attr_enc_printstring, sec_attr_enc_printstring_array, sec_attr_enc_bytes, sec_attr_enc_confidential_bytes, sec_attr_enc_i18n_data, sec_attr_enc_uuid, sec_attr_enc_attr_set, sec_attr_enc_binding, sec_attr_enc_trig_binding } sec_attr_encoding_t;

This data type contains the following elements:

Attribute values must conform to the attribute's encoding type.

sec_attr_value_t

The sec_attr_value_t data type defines the values of attributes.

typedef union sec_attr_u switch (sec_attr_encoding_t attr_encoding) tagged_union { case sec_attr_enc_void: ; case sec_attr_enc_integer: signed32 signed_int; case sec_attr_enc_printstring: sec_attr_enc_printstring_p_t printstring; case sec_attr_enc_printstring_array: [ptr] sec_attr_enc_str_array_t *string_array; case sec_attr_enc_bytes: case sec_attr_enc_confidential_bytes: [ptr] sec_attr_enc_bytes_t *bytes; case sec_attr_enc_i18n_data: [ptr] sec_attr_i18n_data_t *idata; case sec_attr_enc_uuid: uuid_t uuid; case sec_attr_enc_attr_set: [ptr] sec_attr_enc_attr_set_t *attr_set; case sec_attr_enc_binding: [ptr] sec_attr_bind_info_t *binding; } sec_attr_value_t;

This data type contains the following elements:


If attr_encoding is... Then tagged_union contains...
sec_attr_enc_void NULL
sec_attr_enc_integer signed_int (32-bit signed integer)
sec_attr_enc_printstring printstring (string pointer)
sec_attr_enc_printstring_array string_array (pointer to an array of printstrings)
sec_attr_enc_bytes sec_attr_enc_confidential_bytes bytes (pointer to a structure of type sec_attr_enc_bytes_t)
sec_attr_enc_i18n_data idata (pointer to a structure of type sec_attr_i18n_data_t)
sec_attr_enc_uuid uuid (UUID)
sec_attr_enc_attr_set attr_set (pointer to a structure of type sec_attr_enc_attr_set_t)
sec_attr_enc_binding binding (pointer to a structure of type sec_attr_binding_info_t)


sec_attr_t

The sec_attr_t data type defines an attribute.

typedef struct { uuid_t attr_id; sec_attr_value_t attr_value; } sec_attr_t;

This data type contains the following elements:

sec_attr_vec_t

The sec_attr_vec_t data type defines an array of attributes.

typedef struct { unsigned32 num_attrs; [size_is(num_attrs), ptr] sec_attr_t *attrs; } sec_attr_vec_t;

This data type contains the following elements:

Interface UUID for rs_attr

The interface UUID for the rs_attr interface is given by the following:

[ uuid(a71fc1e8-567f-11cb-98a0-08001e04de8c) ] interface rs_attr {

rs_attr_cursor_init()

The rs_attr_cursor_init() operation initializes a scan cursor.

void rs_attr_cursor_init ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [out] unsigned32 *cur_num_attrs, [out] rs_attr_cursor_t *cursor, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The cur_num_attrs parameter contains the current total number of attributes associated with the RS object at the time of this call.

The cursor parameter contains the cursor initialized to the first attribute in the list of attributes associated with this object.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_lookup_by_id()

The rs_attr_lookup_by_id() operation looks up (reads) attribute(s) by UUID.

void rs_attr_lookup_by_id ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in, out] rs_attr_cursor_t *cursor, [in] unsigned32 num_attr_keys, [in] unsigned32 space_avail, [in, size_is(num_attr_keys)] sec_attr_t attr_keys[], [out] unsigned32 *num_returned, [out, size_is(space_avail), length_is(*num_returned)] sec_attr_t attrs[], [out] unsigned32 *num_left, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this lookup operation.

As input, the cursor parameter is an initialized or uninitialized cursor to the RS object. As output, cursor is positioned just past the attributes returned as output to this call.

The num_attr_keys parameter specifies the number of elements in the attr_keys array. If the num_attr_keys is set to 0, this function will return all attributes that the caller is authorized to see.

The space_avail parameter specifies the size of the output attrs array.

The attr_keys[] parameter contains the attribute type UUIDs for the attribute instance(s) requested by this lookup. If the requested attribute type is associated with a query trigger, the *attr_keys.attr_value field may be used to pass in optional information required by the trigger query. If no information is to be passed in the *attr_keys.attr_value field (whether the type indicates a trigger query or not), the *attr_keys.attr_value encoding type should be set to sec_attr_enc_void.

The num_returned parameter specifies the number of attribute instances returned in the attrs array.

The attrs[] parameter contains the attributes retrieved by UUID.

The num_left parameter contains the approximate number of attributes matching the search criteria that could not be returned due to space constraints in the attrs buffer. (This number may not be precise if the server allows updates between successive query calls.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_lookup_no_expand()

The rs_attr_lookup_no_expand() operation reads attributes by UUID without expanding attribute sets to their constituent member attributes.

void rs_attr_lookup_no_expand ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in, out] rs_attr_cursor_t *cursor, [in] unsigned32 num_attr_keys, [in] unsigned32 space_avail, [in, size_is(num_attr_keys)] sec_attr_t attr_keys[], [out] unsigned32 *num_returned, [out, size_is(space_avail), length_is(*num_returned)] sec_attr_t attrs[], [out] unsigned32 *num_left, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

As input, the cursor parameter is an initialized or uninitialized cursor to the RS object. As output, cursor is positioned just past the attributes returned as output to this call.

The num_attr_keys parameter specifies the number of elements in the attr_keys array. If the num_attr_keys is set to 0, this function will return all attributes that the caller is authorized to see.

The space_avail parameter specifies the size of the output attrs array.

The attr_keys[] parameter contains the attribute type UUIDs for the attribute instance(s) requested by this lookup. If the requested attribute type is associated with a query trigger, the *attr_keys.attr_value field may be used to pass in optional information required by the trigger query. If no information is to be passed in the *attr_keys.attr_value field (whether the type indicates a trigger query or not), the *attr_keys.attr_value encoding type should be set to sec_attr_enc_void.

The num_returned parameter specifies the number of attribute instances returned in the attrs array.

The attrs[] parameter contains the attributes retrieved by UUID.

The num_left parameter contains the approximate number of attributes matching the search criteria that could not be returned due to space constraints in the attrs buffer. (This number may not be precise if the server allows updates between successive query calls.)

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_lookup_by_name()

The rs_attr_lookup_by_name() operation looks up (reads) a single attribute by name.

void rs_attr_lookup_by_name ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in, string] char *attr_name, [out] sec_attr_t *attr, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The attr_name parameter is the name of the attribute to be retrieved.

The attr parameter is the first attribute instance of the named type.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_update()

The rs_attr_update() operation writes (and/or creates) an attribute. All attributes are written (created) or else none are modified.

void rs_attr_update ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in] unsigned32 num_to_write, [in, size_is(num_to_write)] sec_attr_t in_attrs[], [out] signed32 *failure_index, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The num_to_write parameter specifies the number of attributes in the in_attrs array.

The in_attrs[] parameter contains the attribute instances to be written.

The failure_index parameter, in an error case, contains the array index of the element in in_attrs that caused this update to fail. If the failure cannot be attributed to a specific attribute, failure_index is set to -1.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_test_and_update()

The rs_attr_test_and_update() operation updates attributes if a set of control attributes retain specified values.

void rs_attr_test_and_update ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in] unsigned32 num_to_test, [in, size_is(num_to_test)] sec_attr_t test_attrs[], [in] unsigned32 num_to_write, [in, size_is(num_to_write)] sec_attr_t update_attrs[], [out] signed32 *failure_index, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The num_to_test parameter specifies the number of control attributes in the test_attrs array.

The test_attrs[] parameter contains control attributes whose types and values must exactly match those of instances on the RS object in order for the update to take place.

The num_to_write parameter specifies the number of attributes in the update_attrs array.

The update_attrs[] parameter contains the attribute instances to be written.

The failure_index parameter, in an error case, contains the array index of the element in in_attrs that caused this update to fail. If the failure cannot be attributed to a specific attribute, failure_index is set to -1.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_delete()

The rs_attr_delete() operation deletes attributes.

void rs_attr_delete ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in] unsigned32 num_to_delete, [in, size_is(num_to_delete)] sec_attr_t attrs[], [out] signed32 *failure_index, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The num_to_delete parameter specifies the number of attributes in the attrs array.

The attrs[] parameter contains the attributes to be deleted.

The failure_index parameter, in an error case, contains the array index of the element in in_attrs that caused this update to fail. If the failure cannot be attributed to a specific attribute, failure_index is set to -1.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_get_referral()

The rs_attr_get_referral() operation obtains a referral to an attribute update site.

void rs_attr_get_referral ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in] uuid_t *attr_id, [out] sec_attr_twr_set_p_t *towers, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The attr_id parameter specifies the UUID of the attribute for which a referral is being sought.

The towers parameter specifies the binding information for a suitable update site.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_get_effective()

The rs_attr_get_effective() operation reads the effective attributes by UUID.

void rs_attr_get_effective ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t component_name, [in] unsigned32 num_attr_keys, [in, size_is(num_attr_keys)] sec_attr_t attr_keys[], [out, ref] sec_attr_vec_t *attr_list, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The component_name parameter identifies the RS object on which to perform this operation.

The num_attr_keys parameter specifies the number of elements in the attr_keys array.

The attr_keys[] parameter contains the attribute type UUIDs for the attribute instance(s) requested by this lookup.

The attr_list parameter contains an attribute vector allocated by the server containing all of the attributes matching the search criteria.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

The rs_attr_schema RPC Interface

This section specifies (in IDL/NDR) the RS's rs_attr_schema RPC interface.

Common Data Types and Constants for rs_attr_schema

The following are common data types and constants used in the rs_attr_schema interface.

sec_attr_acl_mgr_info_t

The sec_attr_acl_mgr_info_t structure contains the access control information defined in a schema entry for an attribute.

typedef struct { uuid_t acl_mgr_type; sec_acl_permset_t query_permset; sec_acl_permset_t update_permset; sec_acl_permset_t test_permset; sec_acl_permset_t delete_permset; } sec_attr_acl_mgr_info_t; typedef [ptr] sec_attr_acl_mgr_info_t *sec_attr_acl_mgr_info_p_t;

This data type contains the following elements:

Refer to Access Control Lists (ACLs) for information on Access Control Lists and the definition of the sec_acl_permset_t data type.

sec_attr_sch_entry_flags_t

The sec_attr_sch_entry_flags_t data type is a flag word used to specify schema entry flags.

typedef unsigned32 sec_attr_sch_entry_flags_t; const unsigned32 sec_attr_sch_entry_none = 0x00000000; const unsigned32 sec_attr_sch_entry_unique = 0x00000001; const unsigned32 sec_attr_sch_entry_multi_inst = 0x00000002; const unsigned32 sec_attr_sch_entry_reserved = 0x00000004; const unsigned32 sec_attr_sch_entry_use_defaults = 0x00000008;

The following values are currently registered:

sec_attr_intercell_action_t

The sec_attr_intercell_action_t data type specifies the action that should be taken by the Privilege (PS) Service when it reads acceptable attributes from a foreign cell. A foreign attribute is acceptable only if there is either a schema entry for the foreign cell or if sec_attr_intercell_act_accept is set to TRUE.

typedef enum { sec_attr_intercell_act_accept, sec_attr_intercell_act_reject, sec_attr_intercell_act_evaluate } sec_attr_intercell_action_t;
This data type contains the following elements:
sec_attr_trig_type_flags_t

The sec_attr_trig_type_flags_t data type is a flag word used to indicate schema trigger types.

typedef unsigned32 sec_attr_trig_type_flags_t; const unsigned32 sec_attr_trig_type_none = 0x00000000; const unsigned32 sec_attr_trig_type_query = 0x00000001; const unsigned32 sec_attr_trig_type_update = 0x00000002;

The following values are currently registered:

sec_attr_acl_mgr_info_set_t

The sec_attr_acl_mgr_info_set_t data type defines an attribute's ACL manager set.

typedef struct { unsigned32 num_acl_mgrs; [size_is(num_acl_mgrs)] sec_attr_acl_mgr_info_p_t mgr_info[]; } sec_attr_acl_mgr_info_set_t;

The structure consists of the following elements:

sec_attr_schema_entry_t

The sec_attr_schema_entry_t data type defines a complete attribute entry for the schema catalog. The entry is identified by both name and UUID. Although either can be used as a retrieval key, the name should be used for interactive access to the attribute and the UUID for programmatic access.

typedef struct { [string, ptr] char *attr_name; uuid_t attr_id; sec_attr_encoding_t attr_encoding; [ptr] sec_attr_acl_mgr_info_set_t *acl_mgr_set; sec_attr_sch_entry_flags_t schema_entry_flags; sec_attr_intercell_action_t intercell_action; sec_attr_trig_type_flags_t trig_types; [ptr] sec_attr_bind_info_t *trig_binding; [string, ptr] char *scope; [string, ptr] char *comment; } sec_attr_schema_entry_t;

This data type contains the following elements:

sec_attr_schema_entry_parts_t

The sec_attr_schema_entry_parts_t data type is a flag word used during an update to specify which fields of an input schema entry (of type sec_attr_schema_entry_t) contain modified information for the update.

typedef unsigned32 sec_attr_schema_entry_parts_t; const unsigned32 sec_attr_schema_part_name = 0x00000001; const unsigned32 sec_attr_schema_part_acl_mgrs = 0x00000002; const unsigned32 sec_attr_schema_part_unique = 0x00000004; const unsigned32 sec_attr_schema_part_reserved = 0x00000008; const unsigned32 sec_attr_schema_part_defaults = 0x00000010; const unsigned32 sec_attr_schema_part_intercell = 0x00000020; const unsigned32 sec_attr_schema_part_trig_types = 0x00000040; const unsigned32 sec_attr_schema_part_trig_bind = 0x00000080; const unsigned32 sec_attr_schema_part_comment = 0x00000100;

This data type contains the following flags:

Interface UUID for rs_attr_schema

The interface UUID for the rs_attr_schema interface is given by the following:

[ uuid(b47c9460-567f-11cb-8c09-08001e04de8c) ] interface rs_attr_schema {

rs_attr_schema_create_entry()

The rs_attr_schema_create_entry() operation creates a new schema entry.

void rs_attr_schema_create_entry ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] sec_attr_schema_entry_t *schema_entry, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The schema_entry parameter identifies the schema entry to be created. Values must be supplied for all of the fields of the input sec_attr_schema_entry_t structure, with the exception of the trig_types, trig_bind, and comment fields, which are all optional.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_delete_entry()

The rs_attr_schema_delete_entry() operation deletes a schema entry. This is a radical operation that will delete or invalidate any existing attributes of this type on nodes dominated by the schema.

void rs_attr_schema_delete_entry ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] uuid_t *attr_id, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object to be deleted.

The attr_id parameter contains the UUID for the attribute type of the entry being deleted.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_update_entry()

The rs_attr_schema_update_entry() operation updates the modifiable fields of a schema entry.

void rs_attr_schema_update_entry ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] sec_attr_schema_entry_parts_t modify_parts, [in] sec_attr_schema_entry_t *schema_entry, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The modify_parts parameter is a flag which identifies which fields of the schema_entry parameter are to be updated. Fields not indicated by modify_parts, or fields which are not permitted to be modified, will retain their current values.

The schema_entry parameter specifies a sec_attr_schema_entry_t data structure whose fields are NULL except for those fields which are being modified (as indicated by the modify_parts parameter).

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

If a field is indicated by its flag in modify_parts, that field from the input schema entry will completely replace the current field of the existing schema entry. All other fields will remain untouched.

Note:
Fields which are arrays of structures (such as acl_mgr_set) and trig_binding) will be completely replaced by the new input array. This operation will not simply add one more element to the existing array.

rs_attr_schema_cursor_init()

The rs_attr_schema_cursor_init() operation initializes a scan cursor.

void rs_attr_schema_cursor_init ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [out] unsigned32 *cur_num_entries, [out] rs_attr_cursor_t *cursor, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The cur_num_entries parameter specifies the current total number of entries in the schema at the time of this call.

The cursor parameter contains the cursor initialized to the first in the list of entries in the named schema.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_scan()

The rs_attr_schema_scan() operation reads a specified number of entries from the named schema object.

void rs_attr_schema_scan ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in, out] rs_attr_cursor_t *cursor, [in] unsigned32 num_to_read, [out] unsigned32 *num_read, [out, size_is(num_to_read), length_is(*num_read)] sec_attr_schema_entry_t schema_entries[] [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

As input, the cursor parameter is an initialized or uninitialized cursor to the schema object. As output, cursor is positioned just past the attributes returned as output to this call.

The num_to_read parameter specifies the size of the schema_entries array; that is, the maximum number of entries to be returned in this call.

The num_read parameter specifies the actual number of entries returned in the schema_entries array.

The schema_entries[] array contains the entries read.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_lookup_by_name()

The rs_attr_schema_lookup_by_name() operation performs a lookup (read) on a schema entry identified by name.

void rs_attr_schema_lookup_by_name ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in, string] char *attr_name, [out] sec_attr_schema_entry_t *schema_entry, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The attr_name parameter is the name that identifies the entry to be read.

The schema_entry parameter contains the entry identified by attr_name.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_lookup_by_id()

The rs_attr_schema_lookup_by_id() operation performs a lookup (read) on a schema entry identified by its UUID.

void rs_attr_schema_lookup_by_id ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] uuid_t *attr_id, [out] sec_attr_schema_entry_t *schema_entry, [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The attr_id parameter contains the UUID of the attribute type identifying the entry to be read.

The schema_entry parameter contains the entry identified by attr_id.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_get_referral()

The rs_attr_schema_get_referral() operation obtains a referral to a schema update site. This function is used when the current schema site yields a sec_schema_site_readonly error. Some replication managers will require all updates for a given object to be directed to a given replica. Clients of the generic schema interface may not know they are dealing with an object that is replicated in this way. This function allows them to recover from this problem and rebind to the proper update site.

void rs_attr_schema_get_referral ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] uuid_t *attr_id, [out] sec_attr_twr_set_p_t *towers, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The attr_id parameter contains the UUID that identifies the schema entry.

The towers parameter contains a pointer to an RPC protocol tower for the schema update site.

The status parameter returns the status of the operation.

rs_attr_schema_get_acl_mgrs()

The rs_attr_schema_get_acl_mgrs() operation retrieves a list of the ACL Manager types that protect those objects that are associated with the named schema. The returned list is valid for use in the acl_mgr_set field of a sec_attr_schema_entry_t schema entry.

void rs_attr_schema_get_acl_mgrs ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] unsigned32 size_avail, [out] unsigned32 *size_used, [out] unsigned32 *num_acl_mgr_types, [out, size_is(size_avail), length_is(*size_used)] uuid_t acl_mgr_types[] [out] rs_cache_data_t *cache_info, [outs error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The size_avail parameter specifies the size of the acl_mgr_types array; that is, the maximum number of ACL manager types that can be returned by this call.

The size_used parameter specifies the actual number of ACL Manager types returned in the array.

The num_acl_mgr_types parameter specifies the total number of ACL Manager types supported for this schema. If this value is greater than size_used, this operation should be called again with a larger acl_mgr_types buffer.

The acl_mgr_types[] array contains the UUIDs for the ACL Manager types that protect the objects associated with this schema.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_attr_schema_aclmgr_strings()

The rs_attr_schema_aclmgr_strings() operation retrieves printable representations for each permission bit that the input ACL Manager type will support.

void rs_attr_schema_aclmgr_strings ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in, ref] uuid_t *acl_mgr_type, [in] unsigned32 size_avail, [out] uuid_t *acl_mgr_type_chain, [out] sec_acl_printstring_t *acl_mgr_info, [out, ref] boolean32 *tokenize, [out] unsigned32 *total_num_printstrings, [out, ref] unsigned32 *size_used, [out, size_is(size_avail), length_is(*size_used)] sec_acl_printstring_t permstrings[], [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter identifies the schema object on which to perform this operation.

The acl_mgr_type parameter contains the UUID of the ACL Manager type for which the printstrings are to be returned.

The size_avail parameter specifies the size of the permstrings array; that is, the maximum number of printstrings that can be returned by this call.

The acl_mgr_type_chain parameter, if not set to uuid_nil, identifies the UUID of the next ACL Manager type in a chain supporting ACL Managers with more than 32 permission bits.

The acl_mgr_info parameter contains printstrings provides the name, help information, and complete set of supported permission bits for this ACL Manager type.

If set, the tokenize parameter specifies that the permission bit strings should be tokenized.

The total_num_printstrings parameter specifies the total number of permission printstrings supported by this ACL manager type. If this value is greater than size_avail, this function should be invoked again with a buffer of the appropriate size.

The size_used parameter contains the number of printstrings returned in the permstrings array.

The permstrings[] array contains the printstrings for each permission supported by this ACL manager type.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

There may be aliases for common permission combinations; by convention simple entries should appear at the beginning of the array, and combinations should appear at the appear at the end. When the tokenize flag is FALSE, the permission printstrings are unambiguous; therefore printstrings for various permissions can be concatenated. When tokenize is TRUE, however, this property does not hold and the strings should be tokenized before input or output.

If the ACL Manager type supports more than 32 permission bits, multiple manager types can be used-one for each 32-bit wide slice of permissions. When this is the case, the acl_mgr_type_chain parameter is set to the UUID of the next ACL Manager type in the set. The final result for the chain returns uuid_nil in the manager_type_chain parameter.

The rs_prop_acct RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_acct RPC interface.

Common Data Types and Constants for rs_prop_acct

The following are common data types and constants used in the rs_prop_acct interface.

rs_prop_acct_add_data_t

The rs_prop_acct_add_data_t data type is used for bulk account add propagations during replica initialization.

The RS server stores only the current key version for most principals. If the principal has multiple key versions, the additional versions must be propagated using rs_prop_acct_add_key_version() (defined in rs_prop_acct_add_key_version() ). Only current keys may be propagated via rs_prop_acct_add() (see rs_prop_acct_add() for its definition).

typedef struct { sec_rgy_login_name_t login_name; sec_rgy_acct_user_t user_part; sec_rgy_acct_admin_t admin_part; rs_acct_key_transmit_t *key; [ptr] rs_acct_key_transmit_t *unix_passwd; sec_rgy_foreign_id_t client; sec_passwd_type_t keytype; } rs_prop_acct_add_data_t;
This data type contains the following elements:
rs_prop_acct_key_data_t

The rs_prop_acct_key_data_t data type is used for bulking up multiple key propagations in the rs_prop_acct_key_add_version() routine.

typedef struct { rs_acct_key_transmit_t *key; boolean32 current; sec_timeval_sec_t garbage_collect; } rs_prop_acct_key_data_t;
This data type contains the following elements:
rs_replica_master_info_t and rs_replica_master_info_p_t

The rs_replica_master_info_t and rs_replica_master_info_p_t data type describes the current master replica.

typedef struct { uuid_t master_id; rs_update_seqno_t master_seqno; unsigned32 master_compat_sw_rev; sec_timeval_t update_ts; rs_update_seqno_t update_seqno; rs_update_seqno_t previous_update_seqno; } rs_replica_master_info_t, *rs_replica_master_info_p_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_prop_acct

The interface UUID and version number for the rs_prop_acct interface are given by the following:

[ uuid(68097130-de43-11ca-a554-08001e0394c7), version(1), pointer_default(ptr) ] interface rs_prop_acct {

rs_prop_acct_add()

The rs_prop_acct_add() operation will propagate account information in bulk to a security replica.

void rs_prop_acct_add ( [in] handle_t rpc_handle, [in] unsigned32 num_accts, [in, ref, size_is(num_accts)] rs_prop_acct_add_data_t accts[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The num_accts parameter identifies the number of accounts described in the accts[] array.

The accts[] parameter provides num_accts security account descriptions.

The master_info parameter provides information on the current master replica (see rs_replica_master_info_t and rs_replica_master_info_p_t ).

If the propq_only flag is set the propagation information will only be added to the propagation queue. It will not be propagated.

The status parameter returns the status of the operation.

rs_prop_acct_delete()

The rs_prop_acct_delete() operation will propagate an account delete to a security replica.

void rs_prop_acct_delete ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the principal name of the account to be deleted.

The master_info parameter provides the security master replica information to the security slave replica.

If the propq_only flag is set the account delete operation is only added to the propagation queue. It is not propagated to the replicas.

The status parameter returns the status of the operation.

rs_prop_acct_rename()

The rs_prop_acct_rename() operation will propagate an account rename to security replicas.

void rs_prop_acct_rename ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *old_login_name, [in] sec_rgy_login_name_t *new_login_name, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The old_login_name parameter identifies the original principal name of the account to be renamed.

The new_login_name parameter identifies the new principal name of the account.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the rename information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_acct_replace()

The rs_prop_acct_replace() operation will propagate an account replace to security replicas.

void rs_prop_acct_replace ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in] rs_acct_parts_t modify_parts, [in] sec_rgy_acct_user_t *user_part, [in] sec_rgy_acct_admin_t *admin_part, [in, ptr] rs_acct_key_transmit_t *key, [in, ref] sec_rgy_foreign_id_t *client, [in] sec_passwd_type_t new_keytype, [in, ptr] rs_acct_key_transmit_t *unix_passwd, [in, ref] sec_timeval_sec_t *time_now, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the account name to replace.

The modify_parts parameter is a flags describing the objects within the account to replace. (see rs_acct_parts_t ).

The user_part parameter describes the user portion of the account to be replaced (see sec_rgy_acct_user_t ).

The admin_part parameter describes the admininstration portion of the account to be replaced (see sec_rgy_acct_admin_t ).

The key parameter indicates a new long-term cryptographic key. (See the description of the key parameter of rs_acct_add().)

The client parameter identifies (by uuid) the principal under whose key the updated key and unix_passwd are encrypted. If client_ids contains NIL uuids, key and unix_passwd are encrypted under a session key.

The new_keytype parameter Indicates the type of the long-term cryptographic key determined by key. (See the description of the new_keytype parameter of rs_acct_add().)

The unix_passwd parameter if not NULL, contains the pickled and encrypted UNIX password (generated by the UNIX crypt() function). The plain arm of the decrypted and unpickled sec_passwd_rec_t contains the UNIX passwd.

The time_now parameter is used for garbage collecting expired versions of multi-version keys.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the account replace information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_acct_add_key_version()

The rs_prop_acct_add_key_version() operation adds specific versions of an account key. This routine is used only during initialization to propagate all extant key types and versions from a surrogate master to an initializing slave.

void rs_prop_acct_add_key_version ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t *login_name, [in] unsigned32 num_keys, [in, ref, size_is(num_keys)] rs_prop_acct_key_data_t keys[], [in] rs_replica_master_info_t *master_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter identifies the account name to propagate the key types to.

The num_keys parameter identifies the number of entries in the keys[] array.

The keys[] parameter. If the current field of keys is TRUE, the key is added as the current version and the garbage_collect field is ignored (current keys are never garbage collected). If current is FALSE, the key is stored as a back-version of the account's key using garbage_collect.

The master_info parameter provides information on the current master replica.

The status parameter returns the status of the operation.

The rs_prop_acl RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_acl RPC interface.

Common Data Types and Constants for rs_prop_acl

The following are common data types and constants used in the rs_prop_acl interface.

rs_prop_acl_data_t

The rs_prop_acl_data_t data type is used for bulk ACL replace propagations during initialization.

typedef struct { sec_acl_component_name_t component_name; uuid_t manager_type; sec_acl_type_t acl_type; sec_acl_list_t *acl_list; } rs_prop_acl_data_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_prop_acl

The interface UUID and version number for the rs_prop_acl interface are given by the following:

[ uuid(591d87d0-de64-11ca-a11c-08001e0394c7), version(1), pointer_default(ptr) ] interface rs_prop_acl {

rs_prop_acl_replace()

The rs_prop_acl_replace() operation will propagate acl replacements in bulk.

void rs_prop_acl_replace ( [in] handle_t rpc_handle, [in] unsigned32 num_acls, [in, size_is(num_acls)] rs_prop_acl_data_t acls[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The num_acls parameter identifies the number of entries in the acls[] array.

The acls[] parameter is an array of num_acls acls to replace.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the acl replacement is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

The rs_prop_attr RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_attr RPC interface.

Common Data Types and Constants for rs_prop_attr

The following are common data types and constants used in the rs_prop_attr interface.

rs_prop_attr_list_t

The rs_prop_attr_list_t data type contains an array of security attributes associated with a security entry.

typedef struct { unsigned32 num_attrs; [size_is(num_attrs)] sec_attr_t attrs[]; } rs_prop_attr_list_t;
This data type contains the following elements:
rs_prop_attr_data_t

The rs_prop_attr_data_t data type contains a component name and property attributes for a bulk propagation operation.

typedef struct { sec_rgy_name_t component_name; rs_prop_attr_list_t *attr_list; } rs_prop_attr_data_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_prop_attr

The interface UUID and version number for the rs_prop_attr interface are given by the following:

[ uuid(0eff23e6-555a-11cd-95bf-0800092784c3), version(1), pointer_default(ptr) ] interface rs_prop_attr {

rs_prop_attr_update()

The rs_prop_attr_update() operation will propagate component property attributes in bulk.

void rs_prop_attr_update ( [in] handle_t rpc_handle, [in] unsigned32 num_prop_attrs, [in, ref, size_is(num_prop_attrs)] rs_prop_attr_data_t prop_attrs[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The num_prop_attrs parameter identifies the number of property attribute entries in the prop_attrs[] array.

The prop_attrs[] parameter contains a component name and an array property attributes associated with than name. There are num_prop_attrs entries in the array.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the property attribute information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_attr_delete()

The rs_prop_attr_delete() operation will

void rs_prop_attr_delete ( [in] handle_t rpc_handle, [in] unsigned32 num_prop_attrs, [in, ref, size_is(num_prop_attrs)] rs_prop_attr_data_t prop_attrs[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The num_prop_attrs parameter identifies the number of property attribute arrays in the prop_attrs[] array.

The prop_attrs[] parameter contains a component name and an array property attributes associated with than name. There are num_prop_attrs entries in the array.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the property attribute delete information is only placed the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

} /* End rs_prop_acl interface */

The rs_prop_attr_schema RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_attr_schema RPC interface.

Common Data Types and Constants for rs_prop_attr_schema

The following are common data types and constants used in the rs_prop_attr_schema interface.

rs_prop_attr_sch_create_data_t

The rs_prop_attr_sch_create_data_t data type contains a component name and an attribute schema definition for a propagation operation.

typedef struct { sec_attr_component_name_t schema_name; sec_attr_schema_entry_t schema_entry; } rs_prop_attr_sch_create_data_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_prop_attr_schema

The interface UUID and version number for the rs_prop_attr_schema interface are given by the following:

[ uuid(0eff260c-555a-11cd-95bf-0800092784c3), version(1), pointer_default(ptr) ] interface rs_prop_attr_sch {

rs_prop_attr_schema_create()

The rs_prop_attr_schema_create() operation propagates in bulk a newly created attribute schema.

void rs_prop_attr_schema_create ( [in] handle_t rpc_handle, [in] unsigned32 num_schemas, [in, ref, size_is(num_schemas)] rs_prop_attr_sch_create_data_t schemas[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The num_schemas parameter identifies the number of entries in the schemas array being propagated.

The schemas[] parameter is an array of size num_schemas containing attribute names and schemas.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the attribute schema create information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_attr_schema_delete()

The rs_prop_attr_schema_delete() operation

void rs_prop_attr_schema_delete ( [in] handle_t rpc_handle, [in] sec_attr_component_name_t schema_name, [in] uuid_t *attr_id, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The schema_name parameter specifies the entity to which the attribute is attached.

The attr_id parameter is the attribute type uuid identifying the schema entry to be deleted

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the attribute schema delete information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_attr_schema_update()

The rs_prop_attr_schema_update() operation

void rs_prop_attr_schema_update ( [in] handle_t rpc_handle, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the attribute schema update information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

} /* End rs_prop_attr_sch interface */

The rs_prop_pgo RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_pgo RPC interface.

Common Data Types and Constants for rs_prop_pgo

The following are common data types and constants used in the rs_prop_pgo interface.

rs_prop_pgo_add_data_t

The rs_prop_pgo_add_data_t data type is used for bulk pgo add propagations during initialization.

typedef struct { sec_rgy_name_t name; sec_rgy_pgo_item_t item; sec_rgy_foreign_id_t client; } rs_prop_pgo_add_data_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_prop_pgo

The interface UUID and version number for the rs_prop_pgo interface are given by the following:

[ uuid(c23626e8-de34-11ca-8cbc-08001e0394c7), version(1), pointer_default(ptr) ] interface rs_prop_pgo {

rs_prop_pgo_add()

The rs_prop_pgo_add() operation propagates PGO add operations in bulk during replica initializations.

void rs_prop_pgo_add ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in] unsigned32 num_pgo_items, [in, size_is(num_pgo_items)] rs_prop_pgo_add_data_t pgo_items[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entries to add.

The num_pgo_items parameter is the number of entries in the pgo_items[] array.

The pgo_items[] parameter is num_pgo_items number of domain PGO items to add.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the PGO add information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_pgo_delete()

The rs_prop_pgo_delete() operation propagates a PGO delete to a security replica.

void rs_prop_pgo_delete ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in, ref] sec_rgy_name_t name, [in] sec_timeval_sec_t cache_info, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entry to delete.

The name parameter identifies the PGO item to delete.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the PGO delete information is only placed on the propagation queue. It is not propagated to security replicas.

The status parameter returns the status of the operation.

rs_prop_pgo_rename()

The rs_prop_pgo_rename() operation propagates a PGO rename to a security replica.

void rs_prop_pgo_rename ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in, ref] sec_rgy_name_t old_name, [in, ref] sec_rgy_name_t new_name, [in] sec_timeval_sec_t cache_info, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entry to rename.

The old_name parameter provides the name the PGO item is changing from.

The new_name parameter provides the name the PGO item is changing tp.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the PGO rename information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_pgo_replace()

The rs_prop_pgo_replace() operation propagates a PGO replace to a security replica.

void rs_prop_pgo_replace ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in, ref] sec_rgy_name_t name, [in, ref] sec_rgy_pgo_item_t *item, [in] sec_timeval_sec_t cache_info, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entry to replace.

The name parameter provides the name the PGO item is replacing.

The item parameter identifies the replacement item information.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the PGO replace information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_pgo_add_member()

The rs_prop_pgo_add_member() operation propagates PGO add member information to a security replica.

void rs_prop_pgo_add_member ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in] sec_rgy_name_t go_name, [in] unsigned32 num_members, [in, size_is(num_members)] sec_rgy_member_t members[], [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entry to add members to. This must be either group or organization.

The go_name parameter provides the PGO name to add members to.

The num_members parameter identifies the number of entries in the members array.

The members[] parameter is an array of num_members members to add.

The master_info parameter provides information on the current master replica.

If the propq_only flage is set the PGO add member information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_pgo_delete_member()

The rs_prop_pgo_delete_member() operation propagates PGO member delete information to security replica.

void rs_prop_pgo_delete_member ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in, ref] sec_rgy_name_t go_name, [in, ref] sec_rgy_name_t person_name, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter identifies the PGO domain of the entry to delete a member from. This must be either group or organization.

The go_name parameter identifies the PGO name to delete the member person_name from.

The person_name parameter identifies the member to to delete from the go_name PGO.

The master_info parameter provides information on the current master replica.

If the propq_only flag is set the PGO member delete information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

} /* End rs_prop_pgo interface */

The rs_prop_plcy RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_plcy RPC interface.

Interface UUID and Version Number for rs_prop_plcy

The interface UUID and version number for the rs_prop_plcy interface are given by the following:

[ uuid(e6ac5cb8-de3e-11ca-9376-08001e0394c7), version(1.1), pointer_default(ptr) ] interface rs_prop_plcy {

rs_prop_properties_set_info()

The rs_prop_properties_set_info() operation propagates registry property information changes to replicas.

void rs_prop_properties_set_info ( [in] handle_t rpc_handle, [in, ref] sec_rgy_properties_t *properties, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The properties parameter contains the registry property information to be updated.

The master_info parameter contains the master registry information.

If the propq_only flag is set the property information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_plcy_set_info()

The rs_prop_plcy_set_info() operation propagates organzation policy information changes to replicas.

void rs_prop_plcy_set_info ( [in] handle_t rpc_handle, [in, ref] sec_rgy_name_t organization, [in, ref] sec_rgy_plcy_t *policy_data, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The organization parameter contains the organization name.

The policy_data parameter contains the organization policy information to be updated.

The master_info parameter contains the master registry information.

If the propq_only flag is set the policy information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_auth_plcy_set_info()

The rs_prop_auth_plcy_set_info() operation propagates account authentication policy to replicas.

void rs_prop_auth_plcy_set_info ( [in] handle_t rpc_handle, [in, ref] sec_rgy_login_name_t *account, [in, ref] sec_rgy_plcy_auth_t *auth_policy, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The account parameter describes the account that the authentication policy belongs to.

The auth_policy parameter contains the account authentication policy to be updated.

The master_info parameter contains the master registry information.

If the propq_only flag is set the policy information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_plcy_set_dom_cache_info()

The rs_prop_plcy_set_dom_cache_info() operation is only used to send the domain cache_info to initialize a slave. The update is not logged; the slave will checkpoint its database to disk when initialization completes.

void rs_prop_plcy_set_dom_cache_info ( [in] handle_t rpc_handle, [in, ref] rs_cache_data_t *cache_info, [in, ref] rs_replica_master_info_t *master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The master_info parameter contains the master registry information.

If the propq_only flag is set the policy information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

} /* End rs_prop_plcy interface */

The rs_prop_replist RPC Interface

This section specifies (in IDL/NDR) the RS's rs_prop_replist RPC interface, which provides RS operations to propagate replica list updates from master to slave.

Interface UUID and Version Number for rs_prop_replist

The interface UUID and version number for the rs_prop_replist interface are given by the following:

[ uuid(B7FB9CE8-DFD4-11CA-8016-08001E02594C), version(1.0), pointer_default(ptr) ] interface rs_prop_replist {

rs_prop_replist_add_replica()

The rs_prop_replist_add_replica() operation will add or replace a replica on the replist.

void rs_prop_replist_add_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] rs_replica_name_p_t rep_name, [in] rs_replica_twr_vec_p_t rep_twrs, [in] rs_replica_master_info_p_t master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter is a pointer to the identifier of the replica to add to the replist.

The rep_name parameter is a pointer to the name of the replica to add to the replist.

The rep_twrs parameter is a pointer to the base tower of the replica to be added.

The master_info parameter is the master replica information.

If the propq_only flag is set the replica information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

rs_prop_replist_del_replica()

The rs_prop_replist_del_replica() operation will delete a replica from the replist.

void rs_prop_replist_del_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] rs_replica_master_info_p_t master_info, [in] boolean32 propq_only, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter is a pointer to the identifier of the replica to add to the replist.

The master_info parameter is the master replica information.

If the propq_only flag is set the replica information is only placed on the propagation queue. It is not propagated to the security replicas.

The status parameter returns the status of the operation.

} /* End rs_prop_replist interface */

The rs_pwd_mgmt RPC Interface

This section specifies (in IDL/NDR) the RS's rs_pwd_mgmt RPC interface, which provides remote operations for password management between a client and the Security daemon.

Common Data Types and Constants for rs_pwd_mgmt

The following are common data types and constants used in the rs_pwd_mgmt interface.

rs_pwd_mgmt_plcy_t

The rs_pwd_mgmt_plcy_t data type specifies the policy attribute set used by the password management server to determine the password policy.

typedef struct { unsigned32 num_plcy_args; [size_is(num_plcy_args)]sec_attr_t plcy[]; } rs_pwd_mgmt_plcy_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_pwd_mgmt

The interface UUID and version number for the rs_pwd_mgmt interface are given by the following:

[ uuid(3139a0e2-68da-11cd-91c7-080009242444), version(1.0), pointer_default(ptr) ] interface rs_pwd_mgmt {

rs_pwd_mgmt_setup()

The rs_pwd_mgmt_setup() operation retrieves the values stored in the pwd_val_type and pwd_mgmt_binding extended registry attributes (ERA), if these attributes exist.

void rs_pwd_mgmt_setup ( [in] handle_t rpc_handle, [in] sec_rgy_login_name_t login_name, [out] sec_attr_bind_info_t **pwd_mgmt_bind_info, [out] rs_pwd_mgmt_plcy_t **plcy_p, [out,ref] signed32 *pwd_val_type, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The login_name parameter specifies the account that is requesting the information.

The pwd_mgmt_bind_info parameter specifies binding information contained in the pwd_mgmt_binding ERA.

The plcy_p parameter contains the attributes that indicate the password policy; that is, the pwd_val_type and pwd_mgmt_binding ERAs.

The pwd_val_type parameter specifies the validation type contained in the pwd_val_type ERA, which can be:

The status parameter returns the status of the operation.

} /* End rs_pwd_mgmt interface */

The rs_qry RPC Interface

This section specifies (in IDL/NDR) the RS's rs_qry RPC interface.

Interface UUID and Version Number for rs_qry

The interface UUID and version number for the rs_qry interface are given by the following:

[ /* V1 format UUID: 3727ee604000.0d.00.00.87.84.00.00.00 */ uuid(3727EE60-4000-0000-0D00-008784000000), version(1) ] interface rs_query {

rs_query_are_you_there()

The rs_query_are_you_there() operation finds an RS server.

[idempotent] void rs_query_are_you_there ( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

} /* End rs_query interface */

The rs_repadm RPC Interface

This section specifies (in IDL/NDR) the RS's rs_repadm RPC interface that provide RS administration operations.

Common Data Types and Constants for rs_repadm

The following are common data types and constants used in the rs_repadm interface.

rs_sw_version_t

The rs_sw_version_t data type specifies the software version of the name service.

typedef unsigned char rs_sw_version_t[64];
rs_replica_info_t

The rs_replica_info_t data type contains information about each replica.

typedef struct { unsigned32 rep_state; uuid_t cell_sec_id; uuid_t rep_id; uuid_t init_id; rs_update_seqno_t last_upd_seqno; sec_timeval_t last_upd_ts; rs_sw_version_t sw_rev; unsigned32 compat_sw_rev; rs_update_seqno_t base_propq_seqno; boolean32 master; boolean32 master_known; uuid_t master_id; rs_update_seqno_t master_seqno; } rs_replica_info_t, *rs_replica_info_p_t;
This data type contains the following elements:

Interface UUID and Version Number for rs_repadm

The interface UUID and version number for the rs_repadm interface are given by the following:

[ uuid(5b8c2fa8-b60b-11c9-be0f-08001e018fa0), version(1.1), pointer_default(ptr) ] interface rs_repadm {

rs_rep_admin_stop()

The rs_rep_admin_stop() operation stops the replica identified by this handle.

void rs_rep_admin_stop ( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

rs_rep_admin_maint()

The rs_rep_admin_maint() operation puts the replica in or out of maintenance mode.

void rs_rep_admin_maint( [in] handle_t rpc_handle, [in] boolean32 in_maintenance, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

If the in_maintenance flag is TRUE the replica is put into maintenance mode. If FALSE it is taken out of maintenance mode.

The status parameter returns the status of the operation.

rs_rep_admin_mkey()

The rs_rep_admin_mkey() operation changes the master key and re-encrypts the database.

void rs_rep_admin_mkey( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

rs_rep_admin_info()

The rs_rep_admin_info() operation gets basic information about a replica such as its state, UUID, latest update sequence number and timestamp, and whether it is the master. This operation also gets the replica's information about the master's UUID and the sequence number when the master was designated.

void rs_rep_admin_info( [in] handle_t rpc_handle, [out] rs_replica_info_t *rep_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_info parameter is a pointer to the replica information returned by call.

The status parameter returns the status of the operation.

rs_rep_admin_info_full()

The rs_rep_admin_info_full() operation gets complete information about a replica such as its state, UUID, protocol towers, latest update sequence number and timestamp, and whether it is the master. This operation also get the replica's information about the master's UUID, protocol towers, and the sequence number when the master was designated.

void rs_rep_admin_info_full( [in] handle_t rpc_handle, [out] rs_replica_info_t *rep_info, [out] rs_replica_twr_vec_p_t *rep_twrs, [out] rs_replica_twr_vec_p_t *master_twrs, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_info parameter is a pointer to the replica information returned by the call.

The rep_twrs parameter is a pointer to the replica towers returned by the call.

The master_twrs parameter is a pointer to the masters towers returned by the call.

The status parameter returns the status of the operation.

rs_rep_admin_destroy()

The rs_rep_admin_destroy() operation is a drastic operation which tells a replica to destroy its database and exit.

void rs_rep_admin_destroy( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

rs_rep_admin_init_replica()

The rs_rep_admin_init_replica() operation initializes or re-initializes the slave identified by rep_id. This is a master-only operation.

void rs_rep_admin_init_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter identifies the slave to be initialized/re-initialized.

The status parameter returns the status of the operation.

rs_rep_admin_change_master()

The rs_rep_admin_change_master() operation changes the master to new_master_id. The master gracefully passes its replica list state and propq to the new master. This is a master-only operation.

void rs_rep_admin_change_master( [in] handle_t rpc_handle, [in] uuid_p_t new_master_id, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The new_master_id parameter is the id of the replica to become the new master.

The status parameter returns the status of the operation.

rs_rep_admin_become_master()

The rs_rep_admin_become_master() operation is a drastic operation to make a slave become the master because the master has died. Normally, the rs_rep_admin_change_master() operation is used to designate a new master; this operation can cause updates to be lost.

void rs_rep_admin_become_master( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

rs_rep_admin_become_slave()

The rs_rep_admin_become_slave() operation is a drastic operation to make a replica which thinks it's the master become a slave.

void rs_rep_admin_become_slave( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

} /* End rs_repadm interface */

The rs_replist RPC Interface

This section specifies (in IDL/NDR) the RS's rs_replist RPC interface. The s_replist interfaces provide RS replica list management services.

Common Data Types and Constants for rs_replist

The following are common data types and constants used in the rs_replist interface.

rs_replica_item_t and rs_replica_item_p_t

The rs_replica_item_t data type contains replica information.

typedef struct { uuid_t rep_id; rs_replica_name_p_t rep_name; boolean32 master; boolean32 deleted; rs_replica_twr_vec_p_t rep_twrs; } rs_replica_item_t, *rs_replica_item_p_t;

This data type contains the following elements:

Replica States

The Replica State describes the current state for each replica.

const unsigned32 rs_c_state_unknown_to_master = 1; const unsigned32 rs_c_state_uninitialized = 2; const unsigned32 rs_c_state_initializing = 3; const unsigned32 rs_c_state_in_service = 4; const unsigned32 rs_c_state_renaming = 5; const unsigned32 rs_c_state_copying_dbase = 6; const unsigned32 rs_c_state_in_maintenance = 7; const unsigned32 rs_c_state_mkey_changing = 8; const unsigned32 rs_c_state_becoming_master = 9; const unsigned32 rs_c_state_closed = 10; const unsigned32 rs_c_state_deleted = 11; const unsigned32 rs_c_state_becoming_slave = 12; const unsigned32 rs_c_state_dup_master = 13;
This state contains the following elements:

rs_replica_prop_t

The rs_replica_prop_t data type specifies the replica propagation state.

typedef unsigned32 rs_replica_prop_t; const rs_replica_prop_t rs_c_replica_prop_init = 1; const rs_replica_prop_t rs_c_replica_prop_initing = 2; const rs_replica_prop_t rs_c_replica_prop_update = 3; const rs_replica_prop_t rs_c_replica_prop_delete = 4;

The following values are currently registered:

rs_replica_prop_info_t

The rs_replica_prop_info_t data type contains information associated with a propagation request.

typedef struct { rs_replica_prop_t prop_type; boolean32 last_upd_inited; rs_update_seqno_t last_upd_seqno; sec_timeval_t last_upd_ts; unsigned32 num_updates; } rs_replica_prop_info_t, *rs_replica_prop_info_p_t;

This data type contains the following elements:

rs_replica_comm_t

The rs_replica_comm_t data type specifies the communication status between master and replica.

typedef unsigned32 rs_replica_comm_t; const rs_replica_comm_t rs_c_replica_comm_ok = 1; const rs_replica_comm_t rs_c_replica_comm_short_failure = 2; const rs_replica_comm_t rs_c_replica_comm_long_failure = 3;

The following values are currently registered:

rs_replica_comm_info_t

The rs_replica_comm_info_t data type contains summary information about the communication state between the master and a replica.

typedef struct { rs_replica_comm_t comm_state; error_status_t last_status; signed32 twr_offset; } rs_replica_comm_info_t, *rs_replica_comm_info_p_t;

This data type contains the following elements:

rs_replica_item_full_t

The rs_replica_item_full_t data type contains public information about a replica. This is the information managed by the master.

typedef struct { uuid_t rep_id; rs_replica_name_p_t rep_name; boolean32 master; boolean32 deleted; rs_replica_prop_info_t prop_info; rs_replica_comm_info_t comm_info; rs_replica_twr_vec_p_t rep_twrs; } rs_replica_item_full_t, *rs_replica_item_full_p_t;

This data type contains the following elements:

Interface UUID and Version Number for rs_replist

The interface UUID and version number for the rs_replist interface are given by the following:

[ uuid(850446B0-E95B-11CA-AD90-08001E0145B1), version(1.0), pointer_default(ptr) ] interface rs_replist {

rs_replist_add_replica()

The rs_replist_add_replica() operation adds a replica to the replica list. This is a master-only operation.

void rs_replist_add_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] rs_replica_name_p_t rep_name, [in] rs_replica_twr_vec_p_t rep_twrs, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter provides the UUID identifier of the replica to add.

The rep_name parameter identifies the string name of the replica. The rep_twrs parameter contains a pointer to the replica tower type.

The status parameter returns the status of the operation.

rs_replist_replace_replica()

The rs_replist_replace_replica() operation replaces information about replica rep_id on the replica list. This is a master-only operation.

void rs_replist_replace_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] rs_replica_name_p_t rep_name, [in] rs_replica_twr_vec_p_t rep_twrs, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id contains the UUID identifier of the replica to be replaced.

The rep_name contains the replica name.

The rep_twrs parameter contains a pointer to the replica tower type.

The status parameter returns the status of the operation.

rs_replist_delete_replica()

The rs_replist_delete_replica() operation deletes the replica identified by rep_id The master may not be deleted with this operation, which is a master-only operation.

void rs_replist_delete_replica( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] boolean32 force_delete, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter identifies the replica to be deleted.

If the force_delete parameter is FALSE, send the delete to the replica identified by rep_id as well as the other replicas. If TRUE, do not send the delete to the replica identified by rep_id; it has been killed off some other way.

The status parameter returns the status of the operation.

rs_replist_read()

The rs_replist_read() operation reads the replica list.

void rs_replist_read( [in] handle_t rpc_handle, [in, out] uuid_t *marker, [in] unsigned32 max_ents, [out] unsigned32 *n_ents, [out, length_is(*n_ents), size_is(max_ents)] rs_replica_item_t replist[], [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The marker parameter specifies the starting item in the replica list to be read. If marker is set to uuid_nil, the read starts at the beginning of the replica list. Information about a specific replica can be read by setting marker to its UUID and max_ents to 1.

The max_ents parameter specifies the number of entries to be read.

The n_ents parameter specifies the number of entries that have been read.

The replist[] array is a pointer array of n_ents rs_replica_item_ts.

The status parameter returns the status of the operation.

rs_replist_read_full()

The rs_replist_read_full() operation reads the replica list, obtaining additional propagation information about each replica.

void rs_replist_read_full( [in] handle_t rpc_handle, [in, out] uuid_t *marker, [in] unsigned32 max_ents, [out] unsigned32 *n_ents, [out, length_is(*n_ents), size_is(max_ents)] rs_replica_item_full_t replist[], [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The marker parameter specifies the starting item in the replica list to be read. If marker is set to uuid_nil, the read starts at the beginning of the replica list. Information about a specific replica can be read by setting marker to its UUID and max_ents to 1. As output, marker contains the uuid of the next replica on the list. When marker contains uuid_nil, there are no more replicas on the list.

The max_ents parameter specifies the number of entries to be read.

The n_ents parameter specifies the number of entries that have been read.

The replist[] array is a pointer array of n_ents rs_replica_item_ts.

The status parameter returns the status of the operation.

} /* End rs_replistinterface */

The rs_repmgr RPC Interface

This section specifies (in IDL/NDR) the RS's rs_repmgr RPC interface. The rs_repmgr interface provides operations between RS replicas.

Common Data Types and Constants for rs_repmgr

The following are common data types and constants used in the rs_repmgr interface.

rs_replica_auth_t and rs_replica_auth_p_t

The rs_replica_auth_t data type contains authentication information used between replicas.

typedef struct { unsigned32 info_type; unsigned32 info_len; [size_is(info_len)] byte info[]; } rs_replica_auth_t, *rs_replica_auth_p_t;

This data type contains the following elements:

Interface UUID and Version Number for rs_repmgr

The interface UUID and version number for the rs_repmgr interface are given by the following:

[ uuid(B62DC198-DFD4-11CA-948F-08001E02594C), version(2.0), pointer_default(ptr) ]

rs_rep_mgr_get_info_and_creds()

The rs_rep_mgr_get_info_and_creds() operation gets a replica's basic state information and credentials in order to authenticate to the replica.

void rs_rep_mgr_get_info_and_creds( [in] handle_t rpc_handle, [out] rs_replica_info_t *rep_info, [out] rs_replica_auth_p_t *rep_auth_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_info pointer contains a structure describing the replica.

The rep_auth_info contains the information to authenticate the replica.

The status parameter returns the status of the operation.

rs_rep_mgr_init()

The rs_rep_mgr_init() operation tells a replica to initialize itself from another replica.

void rs_rep_mgr_init( [in] handle_t rpc_handle, [in] uuid_p_t init_id, [in] unsigned32 nreps, [in, size_is(nreps)] uuid_p_t init_from_rep_ids[], [in, size_is(nreps)] rs_replica_twr_vec_p_t init_from_rep_twrs[], [in] rs_replica_master_info_p_t master_info, [out] uuid_t *from_rep_id, [out] rs_update_seqno_t *last_upd_seqno, [out] sec_timeval_t *last_upd_ts, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The init_id parameter identifies the initialize event to prevent redundant initializations.

The nreps parameter specifies the number of replicas in the init_from_rep_ids array.

The init_from_rep_ids[] array contains a list of replicas from which the slave is to initialize.

The init_from_rep_twrs[] array contains a list of replicas from which the slave is to initialize.

The master_info parameter contains propagation information held by the master replica.

The from_rep_id parameter contains the id of the replica from which the slave has initialized.

The last_upd_seqno parameter contains the sequence number of the last update.

The last_upd_ts parameter contains the timestamp of the last update.

The status parameter returns the status of the operation.

rs_rep_mgr_init_done()

The rs_rep_mgr_init_done() operation lets a slave tell a master that it has finished initializing itself from another replica.

void rs_rep_mgr_init_done( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] uuid_p_t init_id, [in] uuid_p_t from_rep_id, [in] rs_update_seqno_t *last_upd_seqno, [in] sec_timeval_t *last_upd_ts, [in] error_status_t *init_st, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter specifies the replica which has been initialized.

The init_id parameter rs_replist2_master_init_rep_don

The from_rep_id parameter contains the UUID of the replica from which the rep_id replica has initialized.

The last_upd_seqno parameter indicates the last sequence number which was updated.

The last_upd_ts parameter indicates the timestamp the last sequence was updated.

The init_st parameter indicates whether or not the initialization actually succeeded.

The status parameter returns the status of the operation.

rs_rep_mgr_i_am_slave()

The rs_rep_mgr_i_am_slave() operation sends a message from a slave to the master when the slave restarts. The slave sends the master its current tower set and software compatability version.

void rs_rep_mgr_i_am_slave( [in] handle_t rpc_handle, [in] uuid_p_t rep_id, [in] unsigned32 compat_sw_rev, [in] rs_replica_twr_vec_p_t rep_twrs, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_id parameter specifies the UUID of the slave replica that has restarted.

The compat_sw_rev parameter contains the software compatibility version number.

The rep_twrs parameter is a pointer to the slaves tower set.

The status parameter returns the status of the operation.

rs_rep_mgr_i_am_master()

The rs_rep_mgr_i_am_master() operation allows a new master to tell a slave that it is now the master.

void rs_rep_mgr_i_am_master( [in] handle_t rpc_handle, [in] rs_replica_master_info_p_t master_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The master_info parameter supplies the slave with all of the necessary master replica information.

The status parameter returns the status of the operation.

rs_rep_mgr_become_master()

The rs_rep_mgr_become_master() operation lets a master replica tell a slave to become the new master.

void rs_rep_mgr_become_master( [in] handle_t rpc_handle, [in] rs_update_seqno_t base_prop_seqno, [in] rs_replica_master_info_p_t old_master_info, [out] rs_replica_master_info_t *new_master_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The base_prop_seqno parameter is the sequence number of the earliest update currently on the prop queue.

The old_master_info parameter is the master replica information from the current master.

The new_master_info parameter is the master replica information from the new master.

The status parameter returns the status of the operation.

rs_rep_mgr_copy_all()

The rs_rep_mgr_copy_all() operation is a request sent from one replica to another asking the latter replica to push its entire database to the requesting replica.

void rs_rep_mgr_copy_all( [in] handle_t rpc_handle, [in] rs_replica_master_info_p_t copy_master_info, [in] rs_replica_auth_p_t rep_auth_info, [in, ptr] rs_acct_key_transmit_t *encryption_key, [out] rs_update_seqno_t *last_upd_seqno, [out] sec_timeval_t *last_upd_ts, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The copy_master_info parameter contains the master information that the providing replica supplies along with the database updates.

The rep_auth_info parameter includes a session key which is used by the two replicas to authenticate one other.

The encryption_key parameter is a key (pickled and encrypted with the session key) that the providing replica will use to encrypt the account authentication keys during propagation.

If the update is successful, the last_upd_seqno parameter contains the sequence number of the last update.

If the update is successful, the last_upd_ts parameter contains the timestamp of the last update.

The status parameter returns the status of the operation.

rs_rep_mgr_copy_propq()

The rs_rep_mgr_copy_propq() operation carries a request from a slave replica, which is becoming the master, to the old master to send the new master the propagation queue.

void rs_rep_mgr_copy_propq( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

rs_rep_mgr_stop_until_compat_sw()

The rs_rep_mgr_stop_until_compat_sw() operation lets a master replica tell a slave not to run until its software has been updated to the software version number contained in compat_sw_rev.

void rs_rep_mgr_stop_until_compat_sw( [in] handle_t rpc_handle, [in] unsigned32 compat_sw_rev, [in] rs_replica_master_info_p_t master_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The compat_sw_rev parameter specifies the software version number that the replica must have in order to run.

The master_info parameter specifies all of the master replica information. This is necessary to verify sequence updates.

The status parameter returns the status of the operation.

The rs_rpladmn RPC Interface

This section specifies (in IDL/NDR) the RS's rs_rpladmn RPC interface.

Interface UUID and Version Number for rs_rpladmn

The interface UUID and version number for the rs_rpladmn interface are given by the following:

[ uuid(5b8c2fa8-b60b-11c9-be0f-08001e018fa0), version(1) ] interface rs_rpladmn {

rs_rep_admin_stop()

The rs_rep_admin_stop() operation stops the replica identified by rpc_handle.

void rs_rep_admin_stop ( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifes the replica to be stopped.

The status parameter returns the status of the operation.

rs_rep_admin_maint()

The rs_rep_admin_maint() operation puts a replica in or out of maintenance mode.

void rs_rep_admin_maint( [in] handle_t rpc_handle, [in] boolean32 in_maintenance, [out] error_status_t *status );

The rpc_handle parameter identifies the replica to be put into (or out of) maintenance mode.

The in_maintenance parameter specifies the mode in which the replica is to be placed.

The status parameter returns the status of the operation.

rs_rep_admin_mkey()

The rs_rep_admin_mkey() operation changes the master key and re-encrypt the database.

void rs_rep_admin_mkey( [in] handle_t rpc_handle, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The status parameter returns the status of the operation.

} /* End rs_rpladmninterface */

The rs_unix RPC Interface

This section specifies (in IDL/NDR) the RS's rs_unix RPC interface.

Common Data Types and Constants for rs_unix

The following are common data types and constants used in the rs_unix interface.

rs_unix_query_t

The rs_unix_query_t data type specifies the criteria used in a query to the RS for UNIX information.

typedef enum { rs_unix_query_name, rs_unix_query_unix_num, rs_unix_query_none } rs_unix_query_t;

This data type contains the following elements:

rs_unix_query_key_t

The rs_unix_query_key_t data type provides a union to contain the key information for a UNIX query.

typedef union switch (rs_unix_query_t query) { case rs_unix_query_name: struct { signed32 name_len; sec_rgy_name_t name; } name; case rs_unix_query_unix_num: signed32 unix_num; default: ; /* Empty default branch */ } rs_unix_query_key_t;

This data type contains the following elements:

sec_rgy_unix_login_name_t

The sec_rgy_unix_login_name_t data type contains a UNIX login name.

typedef [string] char sec_rgy_unix_login_name_t[sec_rgy_name_t_size];
sec_rgy_unix_gecos_t

The sec_rgy_unix_gecos_t data type contains UNIX gecos data.

typedef [string] char sec_rgy_unix_gecos_t[292];
sec_rgy_unix_passwd_t

The sec_rgy_unix_passwd_t data type contains UNIX account information associated with one entry in the passwd data file.

typedef struct { sec_rgy_unix_login_name_t name; sec_rgy_unix_passwd_buf_t passwd; signed32 uid; signed32 gid; signed32 oid; sec_rgy_unix_gecos_t gecos; sec_rgy_pname_t homedir; sec_rgy_pname_t shell; } sec_rgy_unix_passwd_t;

This data type contains the following elements:

sec_rgy_member_buf_t

The sec_rgy_member_buf_t data type contains a comma-separated ASCII list of group names.

typedef [string] char sec_rgy_member_buf_t[sec_rgy_name_t_size * 10];

sec_rgy_unix_group_t

The sec_rgy_unix_group_t data type contains a principal name and a primary and secondary list of group names with which the principal is associated.

typedef struct { sec_rgy_name_t name; signed32 gid; sec_rgy_member_buf_t members; } sec_rgy_unix_group_t;

This data type contains the following elements:

Interface UUID and Version Number for rs_unix

The interface UUID and version number for the rs_unix interface are given by the following:

[ /* V1 format UUID: 361993c0b000.0d.00.00.87.84.00.00.00 */ uuid(361993C0-B000-0000-0D00-008784000000), version(1) ] interface rs_unix {

rs_unix_getpwents()

The rs_unix_getpwents() operation returns an array of UNIX password account entries.

[idempotent] void rs_unix_getpwents ( [in] handle_t rpc_handle, [in] rs_unix_query_key_t *key, [in] unsigned32 num, [in,out] sec_rgy_cursor_t *cursor, [out] unsigned32 *num_out, [out, last_is(*num_out), max_is(num)] sec_rgy_unix_passwd_t result[], [out] rs_cache_data_t *cache_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The key parameter identifies the entries, either by principal name or by local-ID.

The num parameter specifies the size of the result array; that is, the maximum number of entries that can be returned by this call.

As input, the cursor parameter is an initialized or uninitialized cursor to the RS object. As output, cursor is positioned just past the entries returned as output to this call.

The num_out parameter is the actual number of result entries returned in the result array.

The result[] array contains UNIX account information associated with UNIX passwd data file entries.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The status parameter returns the status of the operation.

rs_unix_getmemberents()

The rs_unix_getmemberents() operation returns an array of UNIX group or organization account entries.

[idempotent] void rs_unix_getmemberents ( [in] handle_t rpc_handle, [in] sec_rgy_domain_t domain, [in] rs_unix_query_key_t *key, [in] signed32 max_num_results, [in,out] sec_rgy_cursor_t *member_cursor, [in,out] sec_rgy_cursor_t *cursor, [out] signed32 *num_members, [out, last_is(*num_members), max_is(max_num_results)] sec_rgy_member_t members[], [out] rs_cache_data_t *cache_info, [out] sec_rgy_unix_group_t *result, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The domain parameter specifies whether the entries are person, group, or organization entries.

The key parameter identifies the entries, either by name or by local-ID.

The max_num_results parameter specifies the size of the members array; that is, the maximum number of entries that can be returned by this call.

As input, the member_cursor parameter is an initialized or uninitialized cursor to the member list. As output, member_cursor is positioned just past the current member entry returned as output to this call.

As input, the cursor parameter is an initialized or uninitialized cursor to the attribute list. As output, cursor is positioned just past the attributes returned as output to this call.

The num_members parameter is the actual number of member entries returned in the members array.

The members[] array contains member entries.

The cache_info parameter indicates cache information (see rs_cache_data_t ).

The result parameter is a UNIX group describing a principal name and the associated primary and secondary group list.

The status parameter returns the status of the operation.

} /* End rs_unix interface */

The rs_update RPC Interface

This section specifies (in IDL/NDR) the RS's rs_update RPC interface. This interface is registered in the nameservice by the master replica so that clients can locate the master.

Interface UUID and Version Number for rs_update

The interface UUID and version number for the rs_update interface are given by the following:

[ uuid(3B11D6A8-2A9C-11CB-BE8A-08001E0238CA), version(1.0), pointer_default(ptr) ] interface rs_update {

rs_rep_admin_info()

The rs_rep_admin_info() operation retrieves basic information about a replica.

void rs_rep_admin_info( [in] handle_t rpc_handle, [out] rs_replica_info_t *rep_info, [out] error_status_t *status );

The rpc_handle parameter identifies the RS server.

The rep_info parameter contains the information about the replica, including its state, UUID, latest update sequence number and timestamp, whether the replica is a master replica, and information about the replica's master.

The status parameter returns the status of the operation.

} /* End rs_update interface */
Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index