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_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.  The possible status code and its meaning is as
       follows:

       rpc_s_ok
             Success.

 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.

 RELATED INFORMATION

   Functions: 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