| ## 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
Output 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
A server can modify the default authorizations by calling rpc_mgmt_set_authorization_fn( ) 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 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_if_ids(3rpc) rpc_mgmt_inq_server_princ_name(3rpc) rpc_mgmt_inq_stats(3rpc) rpc_mgmt_is_server_listening(3rpc) rpc_mgmt_stop_server_listening(3rpc) ##