RS Editor RPC Interfaces

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

• rs_bind for registry binding operations,

• rs_policy for registry policy and properties operations,

• rs_pgo for PGO item management,

• rs_acct for account management,

• rs_misc for miscellaneous registry operations,

• rs_attr for manipulating registry attributes,

• rs_attr_schema for manipulating registry attribute schemas,

• rs_prop_acct for propagating registry account information,

• rs_prop_acl for propagating registry ACL information,

• rs_prop_attr for propagating registry attributes,

• rs_prop_attr_schema for propagating registry attribute schemas,

• rs_prop_pgo for propagating registry PGO items,

• rs_prop_plcy for propagating registry policy information,

• rs_prop_replist for propagating registry replica list,

• rs_repadm for replica administration,

• rs_replist for replica list administration,

• rs_repmgr for replica management,

• rs_rpladmn for replica administration,

• rs_update for updating replica information,

• rs_pwd_mgmt for password management between clients and security daemons,

• rs_qry for finding a registry server, and

• rs_unix for UNIX interface operations.

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:

• in the Access Permsets fields of schema entries

• on ACLs

• in policies regarding their use

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:

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:

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

• Only the Group Manager Type supports ACLE type GROUP_OBJ (GO).

• Only the Principal Manager Type supports ACLE type USER_OBJ (UO).

• ALL Manager Types support all other ACLE types.

This is illustrated in the following two tables:

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 .

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 ):

• Read: "r", 0x00000001

  Disclose an item's information.

• Control (Change, Write-ACL): "c", 0x00000008

  Modify an item's ACL.

• Insert: "i", 0x00000010

  Insert into a directory.
  

• Delete: "d", 0x00000020

  Delete from a directory.

• Test: "t", 0x00000040

  Test a principal's membership in a group or organisation.

• Delete Item: "D", 0x00000080

  Delete an item.

• Name: "n", 0x00000100

  Modify name of an item.

• Fullname: "f", 0x00000200

  Modify the (human-friendly) "full name" (or other annotation).

• Management Info: "m", 0x00000400

  Modify management information.

• Authentication Info: "a", 0x00000800

  Modify authentication information.

• User Info: "u", 0x00001000

  Modify user information.

• Group: "g", 0x00002000

  Add a principal to a group.

• Membership: "M", 0x00004000

  Add or delete principals from a group or organisation.

• Administer: "A", 0x00008000

  Administer the RS.
  

• Initialise: "I", 0x00010000

  Initialise replica list.

• Generic ERA: "O-Z", 0x00020000, 0x00040000, ··· - 0x08000000, 0x10000000

  Generic ERA support only. Not interpreted or assigned meaning by DCE Security Services (controlled by cell administrator). These are marked by an "ERA" in ACL Permissions Supported by RS .

• Serviceability: "s", 0x20000000

  Support ERA Serviceability information for the RS.

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:

• pname

  Principal name associated with the account (subordinate to the sec_rgy_domain_person domain).

• gname

  Group name (subordinate to the sec_rgy_domain_group domain).

• oname

  Organisation name (subordinate to the sec_rgy_domain_org domain).

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:

• source

  The object UUID of the RS server, identifying the RS server/datastore for which a cursor is meaningful.

  Note:

  This is not merely the cell UUID of such an RS server; this is especially significant in a cell with replicated RS servers, as cursors are not meaningful across RS servers/datastores/replicas.

• position

  Position in the datastore of the RS server indicated by source. Its use is RS server/datastore implementation-dependent, in the sense that only the RS server indicated by source can interpret it. In particular, unless specified otherwise in DCE, any implied ordering of the various kinds of data in the RS datastore (for example, the order in which data is returned by multiple invocations of an operation that takes a cursor as in input/output parameter) is also implementation-dependent (for example, alphabetical by principal name, chronological by creation time, random, and so on).

• valid

  If 0 (FALSE), this cursor represents the initial position of an RS datastore; if non-0 (TRUE), a non-initial position (as determined by source and position) is indicated. Clients must set valid to 0 the first time a cursor is used, to initiate an RS datastore retrieval request; after this initial request, clients must treat a cursor as an opaque data object (that is, not accessing any of its fields), interpretable only by the RS server indicated by source.

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):

• site_id

  The object UUID of the RS server to which this modification time information pertains.

• person_dtm

  Time of last deletion (or change) of name, UUID or local-ID, to a PGO item in the principal domain.

• group_dtm

  Time of last deletion (or change) of name, UUID or local-ID, to a PGO item in the group domain.

• org_dtm

  Time of last deletion (or change) of name, UUID or local-ID, to a PGO item in the organisation domain.

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

 

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:

• num_towers

  The number of elements in the towers[] array.

• towers[]

  The actual vector (of size num_towers) of (pointers to) RPC protocol towers. (For the IDL definition of the twr_p_t data type, see Appendix N, IDL Data Type Declarations, of the referenced Open Group DCE 1.1 RPC Specification.)

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_prop_readonly
  Read-only RS site (that is, this replica of the RS server will not service operations that modify data held in the RS datastore). The following are the RS operations that can potentially modify data held in RS datastores (and, therefore, whose service is prevented by the sec_rgy_prop_readonly flag): rdacl_replace(), rs_acct_add(), rs_acct_delete(), rs_acct_rename(), rs_acct_replace(), rs_auth_policy_set_info(), rs_pgo_add(), rs_pgo_add_member(), rs_pgo_delete(), rs_pgo_delete_member(), rs_pgo_rename(), rs_pgo_replace(), rs_policy_set_info(), rs_properties_set_info().

• sec_rgy_prop_auth_cert_unbound

  All certificates (tickets and privilege tickets) generated at this RS site are to be usable at any client site; that is, are not bound to the host from which the client requested the certificate-they contain no client addresses; see Part of Ticket to be Encrypted .)

• sec_rgy_prop_shadow_passwd

  No (protected) passwords are to be transmitted remotely. (Note that the (protected) passwords in question are those relevant to local operating systems-the passwords relevant to the Login Facility specified by DCE are not stored in the RS datastore.) The following are the operations that honour this property: rs_acct_lookup(), rs_login_get_info().

  The word "shadow" is used here in analogy with the notion of "shadow password file", with the same semantics: "as a general statement of intent, passwords, even protected ones, should never be visible". In the cases where (protected) passwords would normally be transmitted, operations that honour this RS property must transmit something else which cannot be interpreted as a (protected) password (the character string of length 1, * (asterisk) (expressed in C-like pseudocode), is recommended, though not required).
  

• sec_rgy_prop_embedded_unix_id

  The UUIDs of principals (except for KDS principals), groups and organisations contain embedded local-IDs (see Security-Version (Version 2) UUIDs ).

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:

• read_version

  The semantics of this field are currently unspecified (it is intended that when it is specified, it will denote a property of the underlying RS datastore, indicating the earliest version of the RS software that can correctly read the datastore). Implementations must set it to 1.

• write_version

  The semantics of this field are currently unspecified (it is intended that when it is specified, it will denote a property of the underlying RS datastore, indicating the earliest version of the RS software that can correctly write the datastore). Implementations must set it to 1.

• minimum_ticket_lifetime

  Cell-wide minimum period of time for which a ticket is to be valid. In the case of the Kerberos authentication service (which is the only authentication service currently supported), "ticket" here is interpreted as "Kerberos ticket" (see Key Distribution (Authentication) Services ), and this field is the same as the cell-wide minimum ticket lifetime listed in RS Information .

• default_certificate_lifetime

  Cell-wide default period of time for which a certificate is to be valid. In the case of Kerberos authentication, "certificate" here is interpreted as "Kerberos ticket-granting-ticket", and this field is the same as the cell-wide default ticket-granting-ticket lifetime listed in RS Information .

• low_unix_id_person

  The minimum local-ID that the RS will assign to a newly created principal.

• low_unix_id_group

  The minimum local-ID that the RS will assign to a newly created group.

• low_unix_id_org

  The minimum local-ID that the RS will assign to a newly created organisation.
  
  

• max_unix_id

  The maximum local-ID that the RS will assign to any newly created entity (in any PGO domain).

• flags

  Flag word.

• realm

  Name of the cell to which the RS belongs (and holds the security information for).

• realm_uuid

  UUID of cell to which RS belongs.

• unauthenticated_quota

  Quota for unauthenticated users. Concerning the general definition of quotas in the RS datastore, see sec_rgy_pgo_item_t . Relative to that definition, the notion of unauthenticated_quota is used for unauthenticated callers of rs_pgo_add() and rs_acct_add().

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_pwd_no_spaces

  Password must not contain the space character.

• sec_rgy_plcy_pwd_non_alpha

  Password must contain a non-alphabetic character.

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:

• passwd_min_len

  The minimum allowable length, in characters (or, equivalently, bytes) for a password. Currently, this value is intended to be enforced by client-side password changing utilities, not by the RS server (this may change in future releases).

• passwd_lifetime

  The lifetime for a password (or, equivalently, a long-term key). Its value must be >= 0. Currently, this value is intended to be enforced by client-side login utilities, not by the RS server (this may change in future releases). See next item.

• passwd_exp_date

  The lifetime for a password (or, equivalently, a long-term key). Its value must be >= 0. Currently, this value is intended to be enforced by client-side login utilities, not by the RS server (this may change in future releases).

  The time at which an account's password will expire (that is, after which logging in to this account will be granted only after the password has been changed), denoted here as acct-passwd-exp-time, is intended to be calculated by the client-side login code via the following algorithm, where passwd_lifetime and passwd_exp_date are from the effective policy for the account (determined by choosing the strictest (smallest, earliest) policy parameters from the account's organisation policy and its cell policy), and where acct-passwd-last-update (whose value must be >= 0) is the time of the most recent change of the account's password, or equivalently, long-term key (thus, it is the same as passwd_dtm in sec_rgy_acct_user_t ):

  • If passwd_lifetime = 0, then acct-passwd-exp-time is equal to passwd_exp_date, unless acct-passwd-last-update is greater (later) than passwd_exp_date (that is, the account's password/key has been changed since passwd_exp_date), in which case, passwd_exp_date is equal to 0 (meaning the password/key does not expire).

  • If passwd_lifetime > 0 and passwd_exp_date = 0, then acct-passwd-exp-time is equal to acct-passwd-last-update + passwd_lifetime.

  • If passwd_lifetime > 0 and passwd_exp_date > 0, then acct-passwd-exp-time is equal to the minimum (earliest) of the two values determined by the two calculations in the two preceding cases, where the value 0 (meaning the password/key does not expire) is considered to be later than any non-zero value.

  The value of acct-passwd-exp-time must be >= 0; the value 0 indicates that the password/key does not expire.

• acct_lifespan

  The length of time an account is valid. Its value must be >= 0. Currently, this value is intended to be enforced by client-side login utilities, not by the RS server (this may change in future releases).

  The time at which an account will expire (that is, after which logging in to this account will be denied), denoted here acct-exp-time, is intended to be calculated by the client-side login code via the following algorithm, where acct_lifespan is from the effective policy for the account (see previous item for definition of this), and where creation_date and expiration_date (both of whose values must be >= 0) are from the account's administrative information (see sec_rgy_acct_admin_t ). (The account can only be reactivated by the administrative action of modifying expiration_date.)

  • If acct_lifespan = 0, then acct-exp-time is equal to expiration_date.

  • If acct_lifespan > 0 and expiration_date = 0, then acct-exp-time is equal to creation_date + acct_lifespan.

  • If acct_lifespan > 0 and expiration_date > 0, then acct-exp-time is equal to the minimum (earliest) of the two values determined by the two calculations in the two preceding cases.

  The value of acct-exp-time must be >= 0; the value 0 indicates that the account does not expire.

• passwd_flags

  Flag word.

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:

• max_ticket_lifetime

  Maximum ticket lifetime. In the case of Kerberos authentication, "ticket" here is interpreted as "Kerberos ticket" (see Key Distribution (Authentication) Services ), and this field is the same as the cell-wide maximum ticket lifetime listed in RS Information .

• max_renewable_lifetime

  Maximum renewable ticket lifetime. In the case of Kerberos authentication, "ticket" here is interpreted as "Kerberos ticket" (see Key Distribution (Authentication) Services ), and this field is same as the cell-wide maximum renewable ticket lifetime listed in RS Information .

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:

• sec_rgy_not_implemented

  Operation not (or not yet) implemented.

• sec_rgy_bad_domain

  Operation not supported on specified domain.

• sec_rgy_object_exists

  Object already exists.

• sec_rgy_name_exists

  Name already exists.

• sec_rgy_unix_id_changed

  Local ID changed on an alias add.

• sec_rgy_is_an_alias

  Query returned an alias but aliases were not allowed to satisfy the query (see rs_pgo_get() ).

• sec_rgy_no_more_entries

  No more matching entries.

• sec_rgy_object_not_found

  Registry object not found.

• sec_rgy_server_unavailable

  Registry server unavailable.

• sec_rgy_not_member_group

  User is not member of specified group.

• sec_rgy_not_member_org

  User is not member of specified organisation.

• sec_rgy_not_member_group_org

  User is not member of specified group and organisation.

• sec_rgy_incomplete_login_name

  Incomplete login name specification.

• sec_rgy_passwd_invalid

  Invalid password.

• sec_rgy_not_authorized

  User is not authorised to update record.

• sec_rgy_read_only

  Registry is read only; updates are not allowed.

• sec_rgy_bad_alias_owner

  PGO alias entry has an invalid owner.

• sec_rgy_bad_data

  Invalid data record.

• sec_rgy_cant_allocate_memory

  Unable to allocate memory.

• sec_rgy_dir_not_found

  Directory not found.

• sec_rgy_dir_not_empty

  Directory not empty.

• sec_rgy_bad_name

  Illegal PGO or directory name.

• sec_rgy_dir_could_not_create

  Unable to create directory.

• sec_rgy_dir_move_illegal

  Directory move not allowed.

• sec_rgy_quota_exhausted

  Principal quota exhausted.

• sec_rgy_foreign_quota_exhausted

  Foreign quota for realm exhausted.

• sec_rgy_no_more_unix_ids

  Local ID space for domain has been exhausted.

• sec_rgy_uuid_bad_version

  UUID version invalid.

• sec_rgy_key_bad_version

  Key version number out of range.

• sec_rgy_key_version_in_use

  Key version number currently in use.

• sec_rgy_key_bad_type

  Key type not supported.

• sec_rgy_crypt_bad_type

  Encrypt/decrypt type not supported.

• sec_rgy_bad_scope

  Scope doesn't name existing directory or PGO.

• sec_rgy_object_not_in_scope

  Object found was not in scope.

• sec_rgy_cant_authenticate

  Can't establish authentication to security server.

• sec_rgy_alias_not_allowed

  Can't add alias for this name or principal (for example, krbtgt).

• sec_rgy_bad_chksum_type

  Checksum type not supported.

• sec_rgy_bad_integrity

  Data integrity error.

• sec_rgy_key_bad_size

  Invalid size for key data.

• sec_rgy_mkey_cant_read_stored

  Can't read stored master key.

• sec_rgy_mkey_bad_stored

  Stored master key is bad.

• sec_rgy_mkey_bad

  Supplied master key is bad.

• sec_rgy_bad_handle

  Bad security context handle.

• sec_rgy_s_pgo_is_required

  PGO/account is required and can't be deleted.

• sec_rgy_host_context_not_avail

  Login context of local host principal not available.

• sec_rgy_mkey_file_io_failed

  Master key file I/O operation failed.

• sec_rgy_tower_rebind_failed

  No usable tower entries.

• sec_rgy_site_not_absolute

  Registry site name must be absolute.

• sec_rgy_bad_nameservice_name

  Invalid nameservice name.

• sec_rgy_log_entry_out_of_range

  Invalid log entry module or operation.

• sec_rgy_era_pwd_mgmt_auth_type

  Authorization type for pwd_mgmt_binding ERA binding cannot be none.

• sec_rgy_passwd_too_short

  Password is too short.

• sec_rgy_passwd_non_alpha

  Passwords must contain at least one non-alphanumeric character.

• sec_rgy_passwd_spaces

  Passwords must contain at least one non-blank character.

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:

• sec_rgy_domain_person

  The principal domain. Its associated stringname is person.

• sec_rgy_domain_group

  The group domain. Its associated stringname is group.

• sec_rgy_domain_org

  The organisation domain. Its associated stringname is org.

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_is_an_alias

  PGO item is an alias.

• sec_rgy_pgo_is_required

  PGO item is required (cannot be deleted).

• sec_rgy_pgo_projlist_ok

  For a group item, indicates that the group can occur in a concurrent group set; that is, can occur as a secondary (non-primary) group associated with some principal or account. Has no meaning on a principal item or an organisation item.

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:

• id

  UUID associated with item. This is the definitive identifier of a PGO item, in the sense that it cannot be changed (see rs_pgo_replace(), rs_pgo_replace() ).

• unix_num

  Local-ID associated with item.

  Note:

  The semantics of the unix_num field does not depend on the sec_rgy_prop_embedded_unix_id property of RS servers (see sec_rgy_properties_flags_t ). The sec_rgy_prop_embedded_unix_id property is important only for those environments/applications that need to extract principals' local-IDs from their principal UUIDs. Other environments/applications are advised instead to use the RS's services (namely, rs_pgo_get(), see rs_pgo_get() ) to do the UUID->local-ID mapping, thereby eliminating their dependency on the sec_rgy_prop_embedded_unix_id property.

• quota

  Quota associated with a principal item (this is not meaningful for group or organisation items).

  The RS server associates to each principal a quota; that is, the maximum number of PGO items and accounts (combined) that may be added to the RS datastore by the principal (by using rs_pgo_add() and/or rs_acct_add()). A quota value of -1 indicates an unlimited quota (no restrictions). If the quota is greater than 0, the quota is decremented on each successful PGO item or account added by the indicated principal. If the quota equals zero, the RS server will fail attempts to add PGO items or accounts (with status sec_rgy_quota_exhausted). The only way to increase a quota value is to explicitly modify the quota field (with rs_pgo_replace() or rs_properties_set_info(); the quota is not incremented on PGO or account deletions operations, for example).

• flags

  Flag word associated with item.

• fullname

  Human-friendly full name of item-or, for that matter, any other human-friendly informative (annotation) data that may be convenient. For example, a PGO item named principal/root might have a fullname of "M. Root, the Superuser". (Note that this example is strictly illustrative-there is no notion in DCE Security that corresponds to the traditional notion of superuser as defined in the security architecture of some local systems.)

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:

• id

  UUID of the object being sought (that is, the item to be matched by the query).

• scope

  The scope of the lookup-by-UUID. This is either the sought object's name, or the name of a directory which is an ancestor (not necessarily an immediate parent) of the sought object.

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:

• unix_num

  Local-ID of the object being sought (that is, the item to be matched by the query).

• scope

  The scope of the lookup-by-local-ID. This is either the sought object's name, or the name of a directory which is an ancestor (not necessarily an immediate parent) of the sought object.

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_name

  Query keyed by name (sec_rgy_name_t).

• rs_pgo_query_id

  Query keyed by UUID (rs_pgo_id_key_t).

• rs_pgo_query_unix_num

  Query keyed by local-ID (rs_pgo_unix_num_key_t).

• rs_pgo_query_next

  Query keyed by the next PGO item following the current cursor position. (See the discussion at rs_pgo_get(), see rs_pgo_get() .)

• rs_pgo_query_none

  Indicates an empty rs_pgo_query_key_t (that is, a non-existent value of this data type). It is used in error cases, to indicate that a item being sought could not be found.

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:

• name

  Name of item.

• item

  RS datastore information associated with item.

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:

• id

  If id is a nil-valued UUID (see referenced Open Group DCE 1.1 RPC Specification), the RS server will generate a non-nil value for the UUID of the added item. If the sec_rgy_prop_embedded_unix_id property is set for the RS server, the generated UUID will be a security-version UUID (see Security-Version (Version 2) UUIDs ) and will contain an embedded local-ID that is either passed in as the unix_num field or generated by the RS server.

  If id is non-nil, it will be used as the UUID of the created item. If the sec_rgy_prop_embedded_unix_id property is set, the UUID will be inspected for the correct (security) version (see Security-Version (Version 2) UUIDs ) and checked to ensure that its embedded local-ID matches the unix_num field (if unix_num is not specified, it will be derived from the embedded local-ID of id).

• unix_num

  If unix_num = -1, the RS server will generate the local-ID of the created item; or, if the RS server's sec_rgy_prop_embedded_unix_id property is set and the id field is non-nil, the local-ID of the created item will be extracted from id.

  If unix_num != -1, it will be used as the local-ID of the created item. If the RS server's sec_rgy_prop_embedded_unix_id property is set and the id field is non-nil, then unix_num must match the local-ID embedded in id.

• quota

  The quota for created principal items. (Has no meaning for group or organisation items.)

• flags

  Flag word associated with this PGO item.

• fullname

  Human-friendly full name associated with this 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: 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:

• rs_pgo_query_name

  This indicates a lookup-by-name search. The PGO item (there can be at most one) at or following item_cursor and having the name specified by (*key).tagged_union.name is to be matched. (No scope information is relevant in this case.)

• rs_pgo_query_id

  This indicates a lookup-by-UUID search. The next PGO item at or following item_cursor and having the UUID specified by (*key).tagged_union.id_key.id, whose name lies within the scope specified by (*key).tagged_union.id_key.scope, is to be matched. Called successively with the same UUID, rs_pgo_get() returns first the distinguished (non-alias) item, then all alias items matching this UUID.

• rs_pgo_query_unix_num

  This indicates a lookup-by-local-ID search. The next PGO item at or following item_cursor and having the local-ID specified by (*key).tagged_union.unix_num_key.unix_num, whose name lies within the scope specified by (*key).tagged_union.unix_num_key.scope, is to be matched. Called successively with the same local-ID, rs_pgo_get() returns first the distinguished (non-alias) item, then all alias items matching this local-ID.

• rs_pgo_query_next

  This indicates that the next PGO item at or following item_cursor, and whose name lies within the scope specified by (*key).tagged_union.scope, is to be matched. Thus, successive queries of this type retrieve all PGO items whose names lie within the indicated scope (or within the entire indicated name_domain, in the case where the scope is the NULL string, indicating the root directory of name_domain).

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_key_person

  The principal name identifies the account; that is, the account (<P, G, O>) is uniquely determined by its <P> component.

  This is the only value required to be supported by this revision of DCE. (That is, an RS datastore in which no principal is associated with more than one account is conformant with DCE.)

• sec_rgy_acct_key_group

  The principal and group names identify the account; that is, the account (<P, G, O>) is uniquely determined by its <P, G> component pair-and moreover this is a minimal query key (that is, the account's <P> component does not constitute a query key).

• sec_rgy_acct_key_org

  The principal, group and organisation names identify the account-and moreover this is a minimal query key (that is, the account's <P, G> component pair does not constitute a query key).

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_admin_valid

  Account is valid for logging in.

• sec_rgy_acct_admin_server

  Allow account to be a server. (That is, this account's principal name may be used as a targeted server name in tickets issued in this cell.)

• sec_rgy_acct_admin_client

  Allow account to be a client. (That is, this account's principal name may be used as a named client name in tickets issued in this cell.)

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_acct_auth_tgt

  Allow issuance of certificates based on (privilege-)ticket-granting-ticket authentication. This must always be set (to 1).

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:

• principal

  The UUID of the principal, within its cell.

• cell

  The UUID of the cell.

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:

• creator

  Identity of the principal who created this account. (Set by the RS server, not directly by the administrator.)

• creation_date

  Time of creation of this account. (Set by the RS server, not directly by the administrator.)

• last_changer

  Identity of the last principal to modify this account. (Set by the RS server, not directly by the administrator.)

• change_date

  Time of last modification of this account. (Set by the RS server, not directly by the administrator.)

• expiration_date

  Last date of validity of this account. (Typically, this indicates a date by which a reactivation of the account must be performed; for example, its password must be changed.)

• good_since_date

  First date of validity of this account. (The KDS will not honour tickets issued before this date.)

• flags

  Flag word for this account.

• authentication_flags

  Authentication flag word for this account.

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_rgy_acct_user_passwd_valid

  This password is good. The absence of this bit forces the user to change his or her password.

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_passwd_none

  Invalid password/key.

• sec_passwd_plain

  Plaintext password.

• sec_passwd_des

  DES key.

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 2³² 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_c_key_version_none

  Invalid key. This is a reserved value to be used in certain service requests; for example, in key lookup requests for the current key whose version number is not known a priori, or in key update requests where the next available version number is to be assigned to the new key.

• sec_passwd_c_version_none

  Invalid password. This is a reserved value to be used in certain service requests; for example, in password initialization for cell initialization when a (new) cell is being added, or when initializing the registry information.

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 = <k₀, ···, k₆₃> is a 64-bit DES key, then it is represented as the 8-byte sec_passwd_des_key_t vector <<k₀, ···, k₇>, ···, <k₅₆, ···, k₆₃>>.

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:

• version_number

  Version number.

• pepper

  A string used to modify the password-to-key generation algorithm (see Registered Password-to-Key Mappings , where it was called salt).

• key

  Either a plaintext password (plain) or a DES key (des_key), depending on whether key_type is equal to sec_passwd_plain or sec_passwd_des, respectively.

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_none

  Invalid checksum.

• sec_chksum_crc32

  CRC^§_G checksum, with seed 0 (see CRC-32 ).

• sec_chksum_rsa_md4

  RSA-MD4-CKSUM which is non-invertible and of length 128 bits, derived from an arbitrary length bit-message (see Checksum Mechanisms and Message Digests 4 and 5 (MD4, MD5) ).

• sec_chksum_rsa_md4_des

  RSA-MD4-DES-CKSUM which is non-invertible and of length 128 bits, derived from an arbitrary length bit-message by prepending an 8 octet confounder and applying the RSA-MD4-CKSUM, and with initialisation vector zero (see Checksum Mechanisms and Message Digests 4 and 5 (MD4, MD5) ).

• sec_chksum_des_cbc

  DES-CBC-CKSUM, with a specified key, and with initialisation vector equal to the same key (see DES-CBC Checksum ).

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:

• chksum_type

  Type of checksum data.

• len

  Length of checksum data. This is 0 when chksum_type is sec_chksum_none; 4 when chksum_type is sec_chksum_crc32; 8 when chksum_type is sec_chksum_des_cbc; 16 when chksum_type is either sec_chksum_rsa_md4 or sec_chksum_rsa_md4_des.

• chksum

  The checksum data itself.

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:

• gecos

  An annotation field, holding any convenient information (similar to the fullname field of sec_rgy_pgo_item_t).

• homedir

  An annotation field, holding any convenient information (typically, this field is interpreted as a user's home directory, in the sense of a POSIX-conformant operating system).

• shell

  An annotation field, holding any convenient information (typically, this field is interpreted as a user's login shell, in the sense of a POSIX-conformant operating system).

• passwd_version_number

  Version number of long-term cryptographic key. (This number is assigned by the RS server, not by an administrator.)

• passwd_dtm

  Time of last password/key update (see sec_rgy_plcy_t ). (This number is assigned by the RS server, not by an administrator.)

• flags

  User flag word.

• passwd

  User's (protected) local password. Its semantics are implementation-dependent. Typical implementations use it to support UNIX password management, as follows.

  If the key input parameter to rs_acct_replace() (see rs_acct_replace() ) has key_type (in the sense of rs_acct_key_transmit_t ) sec_key_plain (that is, the key field of the key parameter contains a plaintext password instead of a DES key), then the RS will use that plaintext and a salt (in the sense of UNIX password management) to generate a UNIX key via crypt().) (If a DES key is passed instead of a plaintext password, the RS will copy the fixed string CIPHER into this UNIX key.)

  This field is ignored on input to rs_acct_add() or rs_acct_replace(), but it contains the UNIX key just described on output from rs_acct_lookup(). Since this passwd field is not used by the authentication services specified in DCE (it merely provides some compatibility and coexistence with the UNIX operating system to clients that care about such things), further details are not relevant to DCE.

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_acct_part_user

  Indicates user-level information.

• rs_acct_part_admin

  Indicates administrative-level information.

• rs_acct_part_passwd

  Indicates password/key information.

• rs_acct_part_login_name

  Indicates datastore query key information.

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:

• enc_pickle_len

  The number of bytes of encrypted data.
  

• enc_pickle

  The encrypted pickle itself.

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_etype_none

  Trivial encryption, as described in Registered Encryption Types (encType-TRIVIAL).

• sec_etype_des_cbc_crc

  DES-CBC-CRC encryption, as described in Registered Encryption Types (encType-DES-CBC-CRC).

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:

• num_bytes

  The number of bytes of network data.

• bytes

  The bytes of network data. This network data is a pickle of some sort.

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:

• etype

  An encryption type for encrypting data. The supported etype's are enumerated in sec_etype_t . The etype is used in conjunction with the session key type and is extracted from the global cryptosystem information. Presently, only one encryption type is supported.

• ekvno

  A version number representing the generic encryption type. Presently, the only version number supported for this generic type is 0.

• ebytes

  The actual bytes of encrypted data that are available to servers.

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):

• enc_type

  Encryption type used by the client to encrypt key and checksum.

• enc_keytype

  Key type of the client's key, used by the client to encrypt key and checksum.

• enc_key_version

  Key version number of the client's key, used by the client to encrypt key and checksum.

• key_pickle_len

  Length (in bytes) of the (unencrypted) sec_passwd_rec_t pickle indicated by key-as opposed to the length of the encrypted pickle (which is already determined by key itself), which might include some padding appended to the unencrypted sec_passwd_rec_t pickle, depending on the encryption algorithm used.
  

• key

  Encrypted sec_passwd_rec_t pickle. In the terminology and notation of (IDL/NDR) Pickles , this (pre-encrypted) pickle's type UUID (H.pkl_type) is d52ef390-49da-11ca-b2ac-08001e022936, and its body bgcolor="#FFFFFF" datastream is an NDR-marshalled sec_passwd_rec_t.

• checksum

  Encrypted sec_chksum_t pickle. In the terminology and notation of (IDL/NDR) Pickles , this (pre-encrypted) pickle's type UUID (H.pkl_type) is d20b05c8-49da-11ca-996d-08001e022936, and its body bgcolor="#FFFFFF" datastream is an NDR-marshalled sec_chksum_t.

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:

• person

  Principal UUID.

• group

  Group UUID.

• org

  Organisation UUID.

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:

• person

  Principal local-ID.

• group

  Group local-ID.

• org

  Organisation local-ID.

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:

• key_parts

  Indicates the minimal portion of the account's <P, G, O> name triple that is required to identify the account.

• sid

  The account's UUID.

• unix_sid

  The account's local-ID.
  

• admin_part

  The account's administration-level information.

• user_part

  The account's user-level information.

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:

• If the rs_acct_part_user bit is set, the account's user-level information is to be replaced with user_part (if this bit is reset, user_part is ignored).

• If the rs_acct_part_admin bit is set, the account's administration-level information is to be replaced with admin_part (if this bit is reset, admin_part is ignored).

• If the rs_acct_part_passwd bit is set, the account's long-term cryptographic key is to be replaced with the keying information contained in (or generatable from) key and new_keytype (if this bit is reset, key and new_keytype are ignored).

• If the rs_acct_part_login_name bit is set, the minimal portion of the account's <P, G, O> name triple that is required to identify the account is to be replaced with key_parts (if this bit is reset, key_parts is ignored).

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):

• Management Info (m), if (*admin_part).flags or (*admin_part).expiration_date is to be changed (to a value different from the previously stored value).

• Authentication Info (a), if (*admin_part).authentication_flags or (*admin_part).good_since_date is to be changed (to a value different from the previously stored value).

• User Info (u), if the key or any field of (*user_part) is to be written (that is, if the rs_acct_part_passwd or rs_acct_part_user bit of the modify_parts parameter is set).

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:

• key_parts

  Indicates the minimal portion of the account's <P, G, O> name triple that is required to identify the account.

• sid

  The account's UUIDs.

• unix_sid

  The account's local-IDs.

• user_part

  The account's user-level information.

• admin_part

  The account's administration-level information.

• policy_data

  The account's effective policy data.
  

• cell_name

  The account's home cell's name.

• cell_uuid

  The account's home cell's UUID.

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:

• source

  Object UUID of the RS server that initialized the cursor.

• object

  The RS object upon which an operation is currently being performed. For schema operations, this object is identified by the schema_name parameter of the operation; for attribute operations, it is identified by the component_name parameter.

• list

  Optionally identifies a list of entries to be operated on, identified by the attr_list parameter of the operation (not used for schema operations).

• entry

  The datastore entry for the current operation. For schema operations, this is the sequential id of the current schema entry. For attribute operations, this is the number of entries remaining in the datastore.

• num_entries_left

  The approximate number of datastore entries that remain to be seen.

• valid

  If 0, an uninitialized cursor. Set to 1 at initialization.

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_none

  The binding is not authenticated.

• sec_attr_bind_auth_dce

  The binding uses DCE shared-secret key authentication.

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:

• info_type

  Specifies whether or not the binding is authenticated.

• dce_info

  A tagged union specifying the method of authorization and the authorization parameters. For unauthenticated bindings (info_type is sec_attr_bind_auth_none), no parameters are supplied. For authenticated bindings (info_type is sec_attr_bind_auth_dce), the following union is supplied:

  • svr_princ_name

    The principal name of the RS server referenced by the binding handle.

  • protect_level

    The protection level for RPC calls made using the binding handle. The protection level determines the degree to which authenticated communications between the client and the server are protected by the authentication service specified by authn_svc.

    If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified protect_level, the level is automatically upgraded to the next higher supported level. The possible protection levels are as follows:

    • rpc_c_protect_level_default

      Uses the default protection level for the specified authentication service. (The default protection level for DCE shared-secret key authentication is rpc_c_protect_level_pkt.)

    • rpc_c_protect_level_none

      Performs no authentication; tickets are not exchanged, session keys are not established, client EPACs or names are not certified, and transmissions are in the clear. Note that although uncertified EPACs should not be trusted, they may be useful for debugging, tracing, and measurement purposes.

    • rpc_c_protect_level_connect

      Authenticates only when the client establishes a relationship with the server.

    • rpc_c_protect_level_call

      Authenticates only at the beginning of each RPC call when the RS server receives the request.

      This level does not apply to RPC calls made over a connection-based protocol sequence (that is, ncacn_ip_tcp). If this level is specified and the binding handle uses a connection-based protocol sequence, the routine uses the rpc_c_protect_level_pkt level instead.

    • rpc_c_protect_level_pkt

      Ensures that all data received is from the expected client.

    • rpc_c_protect_level_pkt_integ

      Ensures and verifies that none of the data transferred between client and server has been modified. This is the highest protection level that is guaranteed to be present in the RPC runtime.

    • rpc_c_protect_level_pkt_privacy

      Authenticates as specified by all of the previous levels and also encrypts each RPC argument value. This is the highest protection level, but is not guaranteed to be present in the RPC runtime.

  • authn_svc

    Specifies the authentication service to use. The exact level of protection provided by the authentication service is specified by protect_level (see above). The supported authentication services are as follows:

    • rpc_c_authn_none

      No authentication; no tickets are exchanged, no session keys established, client EPACs or names are not transmitted, and transmissions are in the clear. Specify rpc_c_authn_none to turn authentication off for RPC calls made using this binding.

    • rpc_c_authn_dce_secret

      DCE shared-secret key authentication.

      
      

    • rpc_c_authn_default

      Default authentication service. The current default authentication service is DCE shared-secret key; therefore, specifying rpc_c_authn_default is equivalent to specifying rpc_c_authn_dce_secret .

  • authz_svc

    Specifies the authorization service implemented by the server for the interface. The validity and trustworthiness of authorization data, like any application data, is dependent on the authentication service and protection level specified. The supported authorization services are as follows:

    • rpc_c_authz_none

      Server performs no authorization. This is valid only if authn_svc is set to rpc_c_authn_none (see above), specifying that no authentication is being performed.

    • rpc_c_authz_name

      Server performs authorization based on the client principal name. This value cannot be used if authn_svc is rpc_c_authn_none (see above).

    • rpc_c_authz_dce

      Server performs authorization using the client's DCE Extended Privilege Attribute Certificate (EPAC) sent to the server with each RPC call made with this binding. Generally, access is checked against DCE Access Control Lists (ACLs).

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_bind_type_string

  RPC string binding.

• sec_attr_bind_type_twrs

  DCE protocol tower representation of bindings.

• sec_attr_bind_type_svrname

  Name of trigger server for lookup in a directory service.

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:

• count

  The number of towers in the array.

• towers[]

  Pointers to RPC protocol towers.

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:

• name_syntax

  The binding type used for this server (see sec_attr_bind_type_t ).

• name

  The actual string representation of the server name.

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:

• string_binding

  RPC string binding.

• twr_set

  DCE protocol tower representation of binding.

• svrname

  Name of trigger server in directory namespace.

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;

• auth_info

  The binding authorization information.

• num_bindings

  The number of binding handles in bindings.

• bindings[]

  An array of RPC binding handles.

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;

• num_strings

  The number of strings in the array.

• strings[]

  An array of pointers to printstrings.

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:

• length

  The size of the data array.

• data[]

  The length of attribute encoding data.

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:

• codeset

  Identifier for the OSF-registered codeset used to encode the data.

• length

  The size of the data array.

• data[]

  The length of attribute encoding data.

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:

• num_members

  The total number of attributes in the attribute set.

• members[]

  An array containing the UUID for each member in the set.

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:

• sec_attr_enc_any

  The attribute value can be of any legal encoding type. This encoding tag is legal for a schema entry only; an attribute entry must contain a specified encoding type.

• sec_attr_enc_void

  The attribute has no value.

• sec_attr_enc_integer

  The attribute value is a signed 32-bit integer.

• sec_attr_enc_printstring

  The attribute value is a printable IDL string in DCE Portable Character Set.

• sec_attr_enc_printstring_array

  The attribute value is an array of printstrings.

• sec_attr_enc_bytes

  The attribute value is a string of bytes. The string is assumed to be a pickle or some other self-describing type.

• sec_attr_enc_confidential_bytes

  The attribute value is a string of bytes that have been encrypted in the key of the principal object to which the attribute is attached. The string is assumed to be a pickle or some other self-describing type. This encoding type is useful only when attached to a principal object, where it is decrypted and encrypted each time the principal's password changes.

• sec_attr_enc_i18n_data

  The attribute value is an internationalized string of bytes with a tag identifying the OSF-registered codeset used to encode the data.

• sec_attr_enc_uuid

  The attribute value is a UUID, of type uuid_t.

• sec_attr_enc_attr_set

  The attribute value is an attribute set, a vector of attribute UUIDs used to associate multiple related attribute instances which are members of the set.

• sec_attr_enc_binding

  The attribute value is a sec_attr_bind_info_t data type that specifies DCE server binding information.

• sec_attr_enc_trig_binding

  This encoding type, returned by an rs_attr_lookup call, informs the client agent of the trigger binding information of an attribute with a query trigger.

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:

• attr_encoding

  An attribute encoding tag that specifies the type of attribute value (see sec_attr_encoding_t ).

• tagged_union

  A tagged union whose contents depend on attr_encoding as follows:

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:

• attr_id

  The UUID of the attribute.

• attr_value

  The attribute value.

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:

• num_attrs

  The number of elements in the attrs array.

• attrs

  An array of pointers to attributes.

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:

• acl_mgr_type

  The UUID of the ACL manager type that supports the object type to which the attribute can be attached. See ACL Managers Supported by RS for a list of ACL Manager Types UUIDs.

• query_permset

  The permission bits needed to access the attribute's value.

• update_permset

  The permission bits needed to update the attribute's value.

• test_permset

  The permission bits needed to test the attribute's value.

• delete_permset

  The permission bits needed to delete an attribute instance.

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_sch_entry_none

  No schema entry flags.

• sec_attr_sch_entry_unique

  Each instance of this attribute type must have a unique value within the cell for the object type implied by the ACL manager type. If this flag is not set, there is no check for uniqueness during attribute writes.

• sec_attr_sch_entry_multi_inst

  This attribute type may be multi-valued; in other words, multiple instances of the same attribute type can be attached to a single object. If this flag is not set, only one instance of this attribute can be attached to a given object.

• sec_attr_sch_entry_reserved

  This schema entry can not be deleted through any interface or by any user. If this flag is not set, then the entry can be deleted by any authorized user.

• sec_attr_sch_entry_use_defaults

  The system-defined default value (if any) for this attribute will be returned on a client query if an instance of this attribute doesn't exist for the queried object. If this flag is not set, no search/return of system default values will take place. (If the attribute does not not exist and this flag is FALSE (0), then no attribute instance will be returned.)

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;

• sec_attr_intercell_act_accept

  If the sec_attr_sch_entry_unique entry flag is set for this schema entry, retain the attribute from the foreign cell only if its value is unique among all attribute instances of this attribute type within the current cell. If sec_attr_sch_entry_unique is not set, retain the foreign attribute.

• sec_attr_intercell_act_reject

  Unconditionally discard the foreign attribute.

• sec_attr_intercell_act_evaluate

  Use the binding information in the trig_binding field of the sec_attr_schema_entry_t for this schema entry to make a sec_attr_trig_query() call to a trigger server. That server determines whether to retain the attribute value, discard the attribute value, or map the attribute to another value(s).

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_trig_type_none

  No trigger type entry flags.

• sec_attr_trig_type_query

  Attribute type is configured with a query trigger. When this flag is set, the following things happen during a lookup request for this attribute type:

  • Client binds to the trigger server using the trig_binding field of the sec_attr_schema_entry_t structure.

  • Client issues a sec_attr_trig_query() call, passing in the attribute keys with the attr_value fields provided by the calling routine that issued the lookup request.

  • If the sec_attr_trig_query() call is successful, client returns output attributes to the caller.

  If this flag is set and an update request is made for this attribute type, the input values of the update request are ignored and the client creates a "stub" attribute instance as a marker. Modifications to the attribute value must occur at the trigger server.

• sec_attr_trig_type_update

  Attribute type is configured with an update trigger. When this flag is set, the following things happen during an update request for this attribute type:

  • Client binds to the trigger server using the trig_binding field of the sec_attr_schema_entry_t structure.

  • Client issues a sec_attr_trig_update() call, passing in the attributes provided by the calling routine that issued the update request.

  • If the sec_attr_trig_update() is successful, the client stores the output attribute(s) in the ERA database and returns the output attribute(s) to the calling routine.

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:

• num_acl_mgrs

  Specifies the number of ACL managers in the ACL manager set.

• mgr_info[]

  Pointers to a set of ACL manager types and their associated permission sets.

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:

• attr_name

  The name of the attribute type.

• attr_id

  The UUID of the attribute type.

• attr_encoding

  The encoding type for this attribute (see sec_attr_encoding_t for a list and description of attribute encoding tags).

• acl_mgr_set

  The ACL manager types (and their associated permission bits) that support objects on which attributes of this type can be created.

• schema_entry_flags

  The schema entry flag settings for this attribute type (see sec_attr_sch_entry_flags_t ).

• intercell_action

  Flag indicating how the Privilege Service will handle attributes from a foreign cell (see sec_attr_intercell_action_t ).

• trig_types

  Flag indicating whether a trigger can perform update or query operations for this attribute type (see sec_attr_trig_type_flags_t ).

• trig_binding

  Binding information for the attribute trigger.

• scope

  Definition of the objects to which this attribute type can be attached.

• comment

  Comment text.

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:

• sec_attr_schema_part_name

  Modified information for the attr_name field.

• sec_attr_schema_part_acl_mgrs

  Modified information for the acl_mgr_set field.

• sec_attr_schema_part_unique

  Not applicable in the current release.

• sec_attr_schema_part_reserved

  Modified information for the sec_attr_sch_entry_reserved setting of the schema_entry_flags field.

• sec_attr_schema_part_defaults

  Modified information for the sec_attr_sch_entry_use_defaults setting of the schema_entry_flags field.

• sec_attr_schema_part_intercell

  Modified information for the intercell_action field.

• sec_attr_schema_part_trig_types

  Not applicable in the current release.

• sec_attr_schema_part_trig_bind

  Modified information for the trig_binding field.

• sec_attr_schema_part_comment

  Modified information for the comment field.

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;

• login_name

  The principal name of the account.

• user_part

  The user portion of the account (see sec_rgy_acct_user_t ).

• admin_part

  The administrative portion of the account (see sec_rgy_acct_admin_t ).

• key

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

• unix_passwd

  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.

• client

  During initialization, client is filled with nil_uuids to indicate that keys are encrypted under a session key. For incremental add propagations, client identifies the principal under whose key the account's key is encrypted.

• keytype

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

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;

• key

  Indicates a new long-term cryptographic account key.

• current

  If current is true the key is added as the current version and garbage_collect 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.

• garbage_collect

  The expiration time of the key.

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;

• master_id

  The uuid_t of the current master replica.

• master_seqno

  The current sequence number corresponding to database updates.

• master_compat_sw_rev

  The software revision number that the master replica is compatible with.

• update_ts

  Timestamp of the latest replica update. This would correspond to the time which the last sequence number was propagated to replicas.

• update_seqno

  The last sequence number to be propagated out to the slave replicas.

• previous_update_seqno

  The previous sequence number that has been propagated to slave replicas.

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;

• component_name

  The component name specifies the entity that the sec_acl is protecting.

• manager_type

  Identifies the manager that is interpreting this sec_acl

• acl_type

  Differentiates between the different types of sec_acls that an object can possess.

• acl_list

  The list of acls for the component_name.

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;

• num_attrs

  The number of attributes within the attrs[] array

• attrs[]

  An array of size num_attrs of security attributes.

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;

• component_name

  The component name for the attribute list.

• attr_list

  The property attributes of component_name.

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;

• schema_name

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

• schema_entry

  Defines the attribute schema for schema_name.

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;

• name

  The PGO name to add.

• item

  The identifying information for the name to add.

• client

  The client that originated the update.

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

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;

• num_plcy_args

  The number of policy attribute entries in the plcy array.

• plcy[]

  An array of policy attributes for password management.

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:

• 0-none (user has no password policy)

• 1-user_select (user must choose his or her own password)

• 2-user_can_select (user can either choose his or her own password or request a system-generated password)

• 3-generation_required (user must use a system-generated password)

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;

• rep_state

  The current replica state (See rs_replica_prop_t ).

• cell_sec_id

  The cell UUID.

• rep_id

  Instance UUID.

• init_id

  The UUID of the current master replica.

• last_upd_seqno

  The replicas latest update sequence number.

• last_upd_ts

  The last sequence update timestamp.

• sw_rev

  The replica software revision number.

• compat_sw_rev

  The compatible software revision number.

• base_propq_seqno

  If this is info from the master, seqno of last update that has been propagated to all replicas. Otherwise, this element is meaningless.

• master

  TRUE, if master replica.

• master_known

  TRUE, if master is known.

• master_id

  The master replica identifier.

• master_seqno

  Seqno when master was designated.

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 );