NAME

rpc_mgmt_set_authorization_fn- establishes an authorisation function for processing remote calls to a server's management routines

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 an authorisation function. The RPC server run-time system automatically calls this function whenever the server run-time system receives a client request to execute one of the remote management routines. The server must implement this function.

Applications specify NULL to unregister a previously registered authorisation function. After such a call, default authorisations are used.

Output

status

Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

DESCRIPTION

Server applications call rpc_mgmt_set_authorization_fn() to establish an authorisation function that controls access to the server's remote management routines. (See Introduction to the RPC API for an explanation of how remote management routines are implemented in servers.)

When a server has not called rpc_mgmt_set_authorization_fn(), or calls with a NULL value for authorization_fn, the server run-time system uses the default authorisations shown in the following table.

Remote Routine	Default Authorisation
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

In the table, "Enabled" indicates that all clients are allowed to execute the remote routine, and "Disabled" indicates that all clients are prevented from executing the remote routine.

A server calls rpc_mgmt_set_authorization_fn() to establish non-default authorisations.

The following C definition for rpc_mgmt_authorization_fn_t shows the prototype for the authorisation function that the server must implement:

 

typedef boolean32 (*rpc_mgmt_authorization_fn_t)
  (
   rpc_binding_handle_t client_binding,           /* in  */
   unsigned32           requested_mgmt_operation, /* in  */
   unsigned32           *status                   /* out */
  );

When a client requests one of the server's remote management functions, the server run-time system calls the authorisation function with two arguments: client_binding and requested_mgmt_operation. The authorisation function uses these arguments to determine whether the calling client is allowed to execute the requested management routine.

The requested_mgmt_operation value depends on the remote management routine requested, as shown in the following table.

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

The authorisation function must handle all of these values.

The authorisation function returns a Boolean value to indicate whether the calling client is allowed access to the requested management function. If the authorisation function returns TRUE, the management routine is allowed to execute. If the authorisation function returns FALSE, the management routine does not execute. In the latter case, the management routine returns a status value to the client that depends on the status value returned by the authorisation function:

• If the status value returned by the authorisation function is either 0 (zero) or rpc_s_ok, then the status value rpc_s_mgmt_op_disallowed is returned to the client by the remote management routine.

• If the authorisation function returns any other status value, that status value is returned to the client by the remote management routine.

The server must implement the authorisation function in a thread-safe manner.

RETURN VALUE

None.

SEE ALSO

rpc_mgmt_ep_unregister()
rpc_mgmt_inq_if_ids()
rpc_mgmt_inq_server_princ_name()
rpc_mgmt_inq_stats()
rpc_mgmt_is_server_listening()
rpc_mgmt_stop_server_listening().

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.