rpc_mgmt_set_authorization_fn(3rpc)
Establishes an authorization function for processing remote calls to a server's management routines
Used by server applications.
Synopsis
#include <dce/rpc.h>
void rpc_mgmt_set_authorization_fn(
rpc_mgmt_authorization_fn_t authorization_fn,
unsigned32 *status);
Parameters
Input
authorization_fn
Specifies a pointer to an authorization function. The RPC server runtime automatically calls this function whenever the server runtime receives a client
request to execute one of the RPC management routines.
Specify NULL to unregister a previously registered authorization function. In this case, the default authorizations (as described later) are used.
The following C definition for rpc_mgmt_authorization_fn_t illustrates the prototype for the authorization function:
typedef boolean32 (*rpc_mgmt_authorization_fn_t)
(
rpc_binding_handle_t client_binding, /* in */
unsigned32 requested_mgmt_operation, /* in
*/
unsigned32 *status /* out */
);
The following table shows the requested_mgmt_operation values passed by the RPC runtime to the authorization function.
| Operation Values Passed to Authorization Function |
| Called Remote Routine | requested_mgmt_operation Value |
| rpc_mgmt_inq_if_ids( ) | rpc_c_mgmt_inq_if_ids |
| rpc_mgmt_inq_server_princ_name( ) | rpc_c_mgmt_inq_princ_name |
| rpc_mgmt_inq_stats( ) | rpc_c_mgmt_inq_stats |
| rpc_mgmt_is_server_listening( ) | rpc_c_mgmt_is_server_listen |
| rpc_mgmt_stop_server_listening( ) | rpc_c_mgmt_stop_server_listen |
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
Description
The rpc_mgmt_set_authorization_fn( ) routine sets up an authorization function to control remote access to the calling server's remote management routines.
If a server does not provide an authorization function, the RPC runtime controls client application access to the server's remote management routines as shown in the next table. In the table, an enabled authorization allows all clients to execute the remote routine and a disabled authorization prevents all clients from executing the remote routine.
| Default Controls for Remote Management Routines | |
| Remote Routine | Default Authorization |
| rpc_mgmt_inq_if_ids( ) | Enabled |
| rpc_mgmt_inq_server_princ_name( ) | Enabled |
| rpc_mgmt_inq_stats( ) | Enabled |
| rpc_mgmt_is_server_listening( ) | Enabled |
| rpc_mgmt_stop_server_listening( ) | Disabled |
The specified function must provide access control for all of the remote management routines.
If the authorization function returns TRUE, the management routine is allowed to execute. If the authorization function returns FALSE, the management routine does not execute, and the called routine returns to the client the status code returned from the rpc_mgmt_authorization_fn_t function. However, if the status code that the rpc_mgmt_authorization_fn_t function returns is 0 (zero) or rpc_s_ok, then the status code rpc_s_mgmt_op_disallowed is returned to the client.
The RPC runtime calls the server-provided authorization function with the following two input arguments:
· The binding handle of the calling client.
· An integer value denoting which management routine the client has called.
Using these arguments, the authorization function determines whether the calling client is allowed to execute the requested management routine. For example, the authorization function can call rpc_binding_inq_auth_client( ) to obtain authentication and authorization information about the calling client and determine if that client is authorized to execute the requested management routine.
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
Related Information
Functions: rpc_mgmt_ep_unregister(3rpc)
rpc_mgmt_inq_server_princ_name(3rpc)
rpc_mgmt_is_server_listening(3rpc)
rpc_mgmt_stop_server_listening(3rpc)