NAME

   rpc_binding_inq_auth_client - Returns authentication and authorization
                                 information from the binding handle for
                                 an authenticated client.  This call is
                                 provided only for compatibility with
                                 pre-1.1 DCE applications. DCE Release
                                 1.1 and later applications should use
                                 the rpc_binding_inq_auth_caller() call.

   Used by server applications.

 SYNOPSIS

   #include <dce/rpc.h>
   #include <dce/id_base.h>

   void rpc_binding_inq_auth_client( rpc_binding_handle_t binding,
                                     rpc_authz_handle_t *privs,
                                     unsigned_char_t **server_princ_name,
                                     unsigned32 *protect_level,
                                     unsigned32 *authn_svc,
                                     unsigned32 *authz_svc,
                                     unsigned32 *status );

 PARAMETERS

   Input

   binding
       Specifies the client binding handle from which to return the
       authentication and authorization information.

   Output

   privs
       Returns a handle to the authorization information for the client
       that made the remote procedure call on binding.
       The server must cast this handle to the data type specified by
       authz_svc.  The following table shows how to cast the return
       value.

                      Casts for Authorization Information
     ____________________________________________________________________
     For authz_svc value:   privs contains this data:   Use this cast:
     ____________________________________________________________________
     rpc_c_authz_none       A NULL value.             None
     rpc_c_authz_name       The calling client's      (unsigned_char_t *)
                            principal name.
     rpc_c_authz_dce        The calling client's        (sec_id_pac_t *)
                            privilege attribute
                            certificate.

        Note that rpc_c_authz_none is valid only if the authn_svc
        parameter is rpc_c_authn_none.
        The data referenced by this parameter is read-only and should not
        be modified by the server.  If the server wants to preserve any
        of the returned data, it must copy the data into server-allocated
        memory.  Specifying NULL prevents the routine from returning this
        parameter.

   server_princ_name
       Returns a pointer to the server principal name specified by the
       client that made the remote procedure call on binding.  The
       content of the returned name and its syntax is defined by the
       authentication service in use.
       Specifying NULL prevents the routine from returning this
       parameter. In this case, the caller does not have to call the
       rpc_string_free() routine.

   protect_level
       Returns the protection level requested by the client that made the
       remote procedure call on binding.  The protection level determines
       the degree to which authenticated communications between the
       client and the server are protected. Specifying NULL prevents the
       routine from returning this parameter.  The possible protection
       levels are as follows:

       rpc_c_protect_level_default
                     Uses the default protection level for the specified
                     authentication service.

       rpc_c_protect_level_none
                     Performs no protection.

       rpc_c_protect_level_connect
                     Performs protection only when the client establishes
                     a relationship with the server.

       rpc_c_protect_level_call
                     Performs protection only at the beginning of each
                     remote procedure call when the server receives the
                     request.

       rpc_c_protect_level_pkt
                     Ensures that all data received is from the expected
                     client.

       rpc_c_protect_level_pkt_integ
                     Ensures and verifies that none of the data
                     transferred between client and server has been
                     modified.

       rpc_c_protect_level_pkt_privacy
                     Performs protection as specified by all of the
                     previous levels and also encrypt each remote
                     procedure call argument value.

   authn_svc
       Returns the authentication service requested by the client that
       made the remote procedure call on binding.
       Specifying NULL prevents the routine from returning this
       parameter.
       The possible authentication services are as follows:

       rpc_c_authn_none
                     No authentication.

       rpc_c_authn_dce_secret
                     DCE shared-secret key authentication.

       rpc_c_authn_dce_public
                     DCE public key authentication (reserved for future
                     use).

       rpc_c_authn_default
                     DCE default authentication service.

   authz_svc
       Returns the authorization service requested by the client that
       made the remote procedure call on binding.

       Specifying NULL prevents the routine from returning this
       parameter.  The possible authorization services are as follows:

       rpc_c_authz_none
                Server performs no authorization. This is valid only
                if the authn_svc parameter is rpc_c_authn_none.

       rpc_c_authz_name
                Server performs authorization based on the client
                principal name.

       rpc_c_authz_dce
                Server performs authorization using the client's DCE
                Privilege Attribute Certificate (PAC) sent to the server
                with each remote procedure call made with binding.
                Generally, access is checked against DCE Access Control
                Lists (ACLs).

   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 codes and their meanings are as
       follows:

       rpc_s_ok      Success.

       rpc_s_invalid_binding
                     Invalid binding handle.

       rpc_s_wrong_kind_of_binding
                     Wrong kind of binding for operation.

       rpc_s_binding_has_no_auth
                     Binding has no authentication information.

 DESCRIPTION

   The rpc_binding_inq_auth_client() routine returns authentication and
   authorization information associated with the client identified by
   binding.  The calling server manager routine can use the returned data
   for authorization purposes.  This call is provided only for
   compatibility with pre-1.1 DCE applications.  DCE Release 1.1 and
   later applications should use the rpc_binding_inq_auth_caller() call.

   The RPC runtime allocates memory for the returned server_princ_name
   parameter.  The server is responsible for calling the
   rpc_string_free() routine for the returned parameter string.

   For applications in which the client side uses the IDL auto_handle
   or implicit_handle attribute, the server side needs to be built with
   the IDL explicit_handle attribute specified in the Attribute
   Configuration File (ACF).  Using explicit_handle provides binding as
   the first parameter to each server manager routine.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_binding_inq_auth_info
              rpc_binding_set_auth_info
              rpc_string_free