ID Map Facility RPC Interface

This chapter specifies the RPC interface supporting the ID Map Facility, namely the secidmap RPC interface (the corresponding ID Map (or sec_id) API is specified in ID Map API ). See ID Map Facility for the background to this chapter.

The secidmap RPC Interface

This section specifies (in IDL/NDR) the secidmap RPC interface, which is supported by every RS server.

Common Data Types and Constants for the secidmap Interface

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

rsec_id_output_selector_t

The rsec_id_output_selector_t data type is used to control the services of the secidmap interface operations.

 

typedef bitset       rsec_id_output_selector_t;
const unsigned32     rsec_id_output_select_gname = 0x1;
const unsigned32     rsec_id_output_select_cname = 0x2;
const unsigned32     rsec_id_output_select_pname = 0x4;
const unsigned32     rsec_id_output_select_cuuid = 0x8;
const unsigned32     rsec_id_output_select_puuid = 0x10;

The following values are currently registered:

• rsec_id_output_select_gname

  Return global PGO name.

• rsec_id_output_select_cname

  Return cell name.

• rsec_id_output_select_pname

  Return cell-relative PGO (principal, group or organisation) name.

• rsec_id_output_select_cuuid

  Return cell UUID.

• rsec_id_output_select_puuid

  Return PGO (principal, group or organisation) UUID.

Selectors (that is, parameters of type rsec_id_output_selector_t) occurring in the operations of this chapter are to some extent considered to be "hints", informing the RS server what services the client is interested in (that is, what information an operation should return in order to be considered successful). Namely, selected bits (that is, set to 1) indicate information that the client is interested in, and unselected bits (that is, set to 0) indicate information that the client is not interested in.

However, there are some situations in which the RS server does or does not return the requested information to clients-without reflecting an error to the client. For example, certain selections do not make sense for certain operations, so the RS server does not return selected information in those cases (this is indicated in the descriptions of the operations, below). Furthermore, in the case of foreign cell referrals (see Global PGO Names ), RS servers are required to always return certain information, whether the client has selected that information or not (this is also indicated in the descriptions below). Finally, the RS server does not consider it an error if no bits at all are selected by the client, or if bits that are currently unregistered are selected (this is not repeated in the descriptions below).

Global PGO Names

Throughout this chapter the notion of global PGO name is used to mean a stringname of one of the following (fully-qualified or partially-qualified) forms:

• /.../cell-name/cell-relative-pgo-name

• /.:/cell-relative-pgo-name

• cell-relative-pgo-name (see sec_rgy_name_t-Short and Long PGO Names ).

Of course, the latter two forms listed here are to be interpreted in the context of (relative to the home cell of) the user of these names.

Note that it is impossible to tell from the mere syntax of a global PGO name whether it names a principal or group or organisation (it may even name all three)-to disambiguate it, a specified PGO naming domain (see sec_rgy_domain_t ) is required. (Concerning naming syntax, see also Integration with Naming Services .)

Status Codes

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

Note:

In cases where exception statuses are not currently described in this specification, it is intended to supply them in the next revision of DCE.

Values:

 

const unsigned32  sec_id_e_name_too_long         = 0x171220d4;
const unsigned32  sec_id_e_bad_cell_uuid         = 0x171220d5;
const unsigned32  sec_id_e_foreign_cell_referral = 0x171220d6;

Descriptions:

• sec_id_e_name_too_long

  A presented name is too long to be processed by RS server's internal datastore implementation.

  For example, the DCE global naming syntax uses an initial /.../, but this may be converted for storage in the RS datastore (depending on the implementation) with an initial krbtgt/ instead; in this case, 2 extra characters are needed to represent the name, so if the name were already at the RS datastore's length limit prior to conversion, it would exceed the limit after the conversion. (In practical implementations, this event is negligible.)
  

• sec_id_e_bad_cell_uuid

  A presented cell UUID is not known to an RS server.

• sec_id_e_foreign_cell_referral

  This status code is not considered a hard failure error; rather, it triggers a foreign cell referral action to occur, as follows. (See also ACL Editors for the general idea of a junction architecture for federated namespace organisation.)

  Namely, when an RS server processes a client request naming a (purported) PGO item that the RS server does not hold in its own datastore, but which it does hold a referral to (referring to another RS server), it resolves the name as far as it can, and returns to the client the required referral information together with a sec_id_e_foreign_cell_referral status code. The client is then expected to retry the operation at the referred-to RS server. This ritual may be iterated.

  Commonly, this referral activity arises when an RS server detects that a prefix of a presented name appears as a KDS principal or cell principal (that is, a principal which is a descendant of the RS server's krbtgt top-level directory of the principal domain). In this case the RS server returns this foreign cell name to the client with a sec_id_e_foreign_cell_referral status code, so the client can bind to an RS server in the foreign cell and retry the operation. (For RS binding, see RS Binding; rs_bind Interface and sec_rgy_bind API and Registry API .)

  This discussion of referrals has been a general one, necessarily leaving some details vague. Those details are to be supplied in explicit instances of referrals (as, for example, the operations specified in this chapter).

Interface UUID and Version Number for the secidmap Interface

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

 

[uuid(0d7c1e50-113a-11ca-b71f-08001e01dc6c), version(1.0)]
interface secidmap
{ 
/* begin running listing of secidmap interface */

rsec_id_parse_name()

The rsec_id_parse_name() operation parses a global PGO name into its cell name and a cell-relative PGO name constituents, together with the UUIDs associated with them (depending on selected options).

 

void
rsec_id_parse_name (
    [in]        handle_t                    rpc_handle,
    [in]        sec_rgy_domain_t            name_domain,
    [in]        sec_rgy_name_t              global_name,
    [in]        rsec_id_output_selector_t   selector,
    [out]       sec_rgy_name_t              cell_namep,
    [out]       uuid_t                      *cell_idp,
    [out]       sec_rgy_name_t              princ_namep,
    [out]       uuid_t                      *princ_idp,
    [out]       error_status_t              *status );

The rpc_handle parameter identifies the target RS server.

The name_domain parameter indicates the PGO domain of interest.

The global_name parameter indicates the global PGO name to be parsed.

The selector parameter indicates the information to be returned:

• If the rsec_id_output_select_gname bit is selected, it is ignored.

• If the rsec_id_output_select_cname bit is selected, then the parsed cell name is returned in cell_namep.

• If the rsec_id_output_select_pname bit is selected, then the parsed cell-relative PGO name is returned in princ_namep.

• If the rsec_id_output_select_cuuid bit is selected, then the parsed cell UUID is returned in cell_idp.

• If the rsec_id_output_select_puuid bit is selected, then the parsed PGO UUID is returned in princ_idp.

The cell_namep parameter indicates the parsed cell name. In the case of a foreign cell referral, it indicates the referred-to foreign cell.

The cell_idp parameter indicates the parsed cell UUID.

The princ_namep parameter indicates the parsed cell-relative PGO name.

The princ_idp parameter indicates the parsed PGO name.

The status parameter returns the status of the operation.

Required rights: No permissions are required, unless the rsec_id_output_select_puuid bit is selected; in that case, this operation succeeds only if the calling client has some permission (of any kind) on the PGO item indicated by name_domain and global_name (and if the client does not have such permission, the operation fails completely; that is, the RS server does not fill in all but the princ_idp parameter).

rsec_id_gen_name()

The rsec_id_gen_name() operation generates a global PGO name, and parses it into its associated cell name and cell-relative name, from specified cell and PGO UUIDs (depending on selected options).

 

void
rsec_id_gen_name (
    [in]        handle_t                    rpc_handle,
    [in]        sec_rgy_domain_t            name_domain,
    [in]        uuid_t                      *cell_idp,
    [in]        uuid_t                      *princ_idp,
    [in]        rsec_id_output_selector_t   selector,
    [out]       sec_rgy_name_t              global_name,
    [out]       sec_rgy_name_t              cell_namep,
    [out]       sec_rgy_name_t              princ_namep,
    [out]       error_status_t              *status );

The rpc_handle parameter identifies the target RS server.

The name_domain parameter indicates the PGO domain of interest.

The cell_idp parameter indicates the cell UUID.

The princ_idp parameter indicates the PGO UUID.

The selector parameter indicates the information to be returned:

• If the rsec_id_output_select_gname bit is selected, then the generated global PGO name is returned in global_name.

• If the rsec_id_output_select_cname bit is selected, then the generated cell name is returned in cell_namep.

• If the rsec_id_output_select_pname bit is selected, then the generated cell-relative PGO name is returned in princ_namep.

• If the rsec_id_output_select_cuuid bit is selected, it is ignored.

• If the rsec_id_output_select_puuid bit is selected, it is ignored.

The global_name parameter indicates the generated global PGO name.

The cell_namep parameter indicates the generated cell name. In the case of a foreign cell referral, it indicates the referred-to foreign cell.

The princ_namep parameter indicates the generated PGO name.

The status parameter returns the status of the operation.

Note:

A sec_id_e_foreign_cell_referral status is generated by this operation only if one of the bits rsec_id_output_select_gname or rsec_id_output_select_pname is selected. Otherwise, the RS server either already holds the required information, or it doesn't hold enough information to generate a referral.

Required rights: This operation succeeds only if the calling client has some permission (of any kind) on the PGO item determined by the specified UUIDs (cell_idp, princ_idp).

rsec_id_parse_name_cache()

The rsec_id_parse_name_cache() operation is identical to rsec_id_parse_name(), with the addition of cache management.

 

void
rsec_id_parse_name_cache (
    [in]        handle_t                    rpc_handle,
    [in]        sec_rgy_domain_t            name_domain,
    [in]        sec_rgy_name_t              global_name,
    [in]        rsec_id_output_selector_t   selector,
    [out]       sec_rgy_name_t              cell_namep,
    [out]       uuid_t                      *cell_idp,
    [out]       sec_rgy_name_t              princ_namep,
    [out]       uuid_t                      *princ_idp,
    [out]       rs_cache_data_t             *cache_info,
    [out]       error_status_t              *status );

The cache_info parameter indicates cache information (see rs_cache_data_t ).

Required rights: Same as rsec_id_parse_name().

rsec_id_gen_name_cache()

The rsec_id_gen_name_cache() operation is identical to rsec_id_gen_name(), with the addition of cache management.

 

void
rsec_id_gen_name_cache (
    [in]        handle_t                    rpc_handle,
    [in]        sec_rgy_domain_t            name_domain,
    [in]        uuid_t                      *cell_idp,
    [in]        uuid_t                      *princ_idp,
    [in]        rsec_id_output_selector_t   selector,
    [out]       sec_rgy_name_t              global_name,
    [out]       sec_rgy_name_t              cell_namep,
    [out]       sec_rgy_name_t              princ_namep,
    [out]       rs_cache_data_t             *cache_info,
    [out]       error_status_t              *status );

} /* end running listing of secidmap interface */

The cache_info parameter indicates cache information (see rs_cache_data_t ).

Required rights: Same as rsec_id_gen_name().