NAME

   rpc_binding_inq_auth_info - Returns authentication and authorization
                               information from a server binding handle

   Used by client applications.

 SYNOPSIS

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

   void rpc_binding_inq_auth_info(
                           rpc_binding_handle_t binding,
                           unsigned_char_t **server_princ_name,
                           unsigned32 *protect_level,
                           unsigned32 *authn_svc,
                           rpc_auth_identity_handle_t *auth_identity,
                           unsigned32 *authz_svc,
                           unsigned32 *status );

 PARAMETERS

   Input

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

   Output

   server_princ_name
       Returns a pointer to the expected principal name of the server
       referenced by 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 used for remote procedure calls made
       with binding.  The protection level determines the degree to which
       authenticated communications between the client and the server are
       protected.  Note that the returned level may be different from the
       level specified for protect_level on the call to
       rpc_binding_set_auth_info().  If the RPC runtime or the RPC
       protocol in the bound protocol sequence does not support a
       specified level, the level is automatically upgraded to the next
       higher supported level.

       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 parameter value.

   authn_svc
       Returns the authentication service used for remote procedure calls
       made with binding.
       Specifying NULL prevents the routine from returning this argument.
       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.

   auth_identity
       Returns a handle for the data structure that contains the client's
       authentication and authorization credentials.  This parameter must
       be cast as appropriate for the authentication and authorization
       services established via rpc_binding_set_auth_info().
       When using the rpc_c_authn_dce_secret authentication service and
       any authorization service, this value must be a sec_login_handle_t
       obtained from one of the following routines:

         + sec_login_setup_identity()

         + sec_login_get_current_context()

         + sec_login_newgroups()

   These routines are described in Chapter 5 of this manual.
   Specifying NULL prevents the routine from returning this parameter.

   authz_svc
       Returns the authorization service used for remote procedure calls
       made with 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_info() routine returns authentication and
   authorization information associated with the specified server binding
   handle.  The calling client associates the authentication and
   authorization data with the server binding handle by a prior call to
   the rpc_binding_set_auth_info() routine.

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

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_binding_set_auth_info
              rpc_string_free