NAME

rpc_mgmt_set_authorization_fn - 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_fnSpecifies 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:

Table 0-0.  Operation Values Passed to Authorization Function

Output

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not.  The possible status codes and their meanings are as follows:

rpc_s_okSuccess. 

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 following table.  In the table, an "enable" authorization allows all clients to execute the remote routine and a "disable" authorization prevents all clients from executing the remote routine. 

Table 0-0.  Default Controls for Remote Management Routines

A server can modify the default authorizations by calling the rpc_mgmt_set_authorization_fn routine to specify an authorization function.  When an authorization function is provided, the RPC runtime automatically calls that function to control the execution of all remote management routines called by clients. 

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 a rpc_s_not_authorized status code 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 the rpc_binding_inq_auth_client routine to obtain authentication and authorization information about the calling client and determine if that client is authorized to execute the requested management routine. 

NOTES

For this release, the RPC authentication (RPC auth) routines are not implemented, nor is an independent security service provided. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_mgmt_ep_unregister(3), rpc_mgmt_inq_if_ids(3), rpc_mgmt_inq_server_princ_name(3), rpc_mgmt_inq_stats(3), rpc_mgmt_is_server_listening(3), rpc_mgmt_stop_server_listening(3)