Previous section.

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

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:

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:

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:

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:

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:

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().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index