NAME

   rpc_binding_set_auth_info - Sets authentication and authorization
                               information for a server binding handle

   Used by client applications.

 SYNOPSIS

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

   void rpc_binding_set_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 for which to set the
       authentication and authorization information.

   server_princ_name
       Specifies the principal name of the server referenced by binding.
       The content of the name and its syntax is defined by the
       authentication service in use.

       A client that does not know the server principal name can call
       the rpc_mgmt_inq_server_princ_name() routine to obtain the
       principal name of a server that is registered for the required
       authentication service.  Using a principal name obtained in this
       way means that the client is interested in one-way authentication.
       In other words, it means that the client does not care which
       server principal received the remote procedure call request.  The
       server, though, still verifies that the client is who the client
       claims to be.

   protect_level
       Specifies the protection level for remote procedure calls made
       using binding.  The protection level determines the degree to
       which authenticated communications between the client and the
       server are protected by the authentication service specified by
       authn_svc.

       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.
       The possible protection levels are as follows:

       rpc_c_protect_level_default
                    Uses the default protection level for the specified
                    authentication service.  The default protection
                    level for the DCE shared-secret key authentication
                    service is rpc_c_protect_level_pkt_integ.

       rpc_c_protect_level_none
                    Performs no authentication: tickets are not
                    exchanged, session keys are not established, client
                    PACs or names are not certified, and transmissions
                    are in the clear.  Note that although uncertified
                    PACs should not be trusted, they may be useful for
                    debugging, tracing, and measurement purposes.

       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.  This level does not apply to remote
                    procedure calls made over a connection-based
                    protocol sequence (that is, ncacn_ip_tcp).  If this
                    level is specified and the binding handle uses a
                    connection-based protocol sequence, the routine uses
                    the rpc_c_protect_level_pkt level instead.

       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.  This is the highest protection level that
                    is guaranteed to be present in the RPC runtime.

       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.  This is the highest
                    protection level, but it may not be available in
                    the RPC runtime.

   authn_svc
       Specifies the authentication service to use. The exact level of
       protection provided by the authentication service is specified
       by the protect_level parameter.  The supported authentication
       services are as follows:

       rpc_c_authn_none
                    No authentication:  no tickets are exchanged, no
                    session keys established, client PACs or names are
                    not transmitted, and transmissions are in the clear.
                    Specify rpc_c_authn_none to turn authentication off
                    for remote procedure calls made using binding.

       rpc_c_authn_dce_secret
                    DCE shared-secret key authentication.

       rpc_c_authn_default
                    DCE default authentication service.  The current
                    default authentication service is DCE shared-secret
                    key; therefore, specifying rpc_c_authn_default is
                    equivalent to specifying rpc_c_authn_dce_secret.

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

       rpc_c_authn_winnt
                    Authentication via Microsoft NT Lan Manager (only
                    available on Windows NT and OpenVMS).  This allows
                    OpenVMS applications to authenticate with a Windows
                    NT domain security server.

   auth_identity
       Specifies a handle for the data structure that contains the
       client's authentication and authorization credentials
       appropriate for the selected authentication and authorization
       services.  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()

         + rpc_winnt_set_auth_identity

   Specify NULL to use the default security login context for the current
   address space.

   authz_svc
       Specifies the authorization service implemented by the server
       for the interface of interest.  The validity and trustworthiness
       of authorization data, like any application data, is dependent on
       the authentication  service and protection level specified.  The
       supported 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, specifying
                 that no authentication is being performed.

       rpc_c_authz_name
                 Server performs authorization based on the client
                 principal name.   This value cannot be used if authn_svc
                 is rpc_c_authn_none.

       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).  This value cannot be
                 used if authn_svc is rpc_c_authn_none.

   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 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_unknown_authn_service
                     Unknown authentication service.

       rpc_s_authn_authz_mismatch
                     Requested authorization service is not supported by
                     the requested authentication service.

       rpc_s_unsupported_protect_level
                     Requested protection level is not supported.

 DESCRIPTION

   The rpc_binding_set_auth_info() routine sets up the specified server
   binding  handle so that it can be used to make authenticated remote
   procedure calls that include authorization information.

   Unless a client calls rpc_binding_set_auth_info() with the parameters
   to set establish authentication and authorization methods, all remote
   procedure calls made on the binding binding handle are unauthenti-
   cated.Some authentication services (authn_svc) may need to
   communicate with the Security service to perform this operation.
   Otherwise, they may receive the rpc_s_comm_failure status.

   The authn_svc parameter specifies the authentication service to use.
   Since currently, there is only one available authentication service
   (DCE shared-secret key), the parameter currently functions to specify
   whether or not rpc calls will be authenticated and client PACs
   certified. If authentication is chosen, the protect_level parameter
   can specify a variety of protection levels, ranging from no
   authentication to the highest level of authentication and encryption.
   If the protect_level parameter is set to rpc_c_protect_level_none, no
   authentication is performed, regardless of the authentication service
   chosen.

   The authz_svc parameter specifies the authorization service to use.
   If no authentication has been chosen (authn_svc of rpc_c_authn_none),
   then no authorization (authz_svc of rpc_c_authz_none) must be chosen
   as well.  If authentication will be performed, you have two choices
   for authorization:  name-based authorization and DCE authorization.
   The use of name based_authorization, which provides a server with a
   client's principal name, is not recommended.  DCE authorization uses
   PACs, a trusted mechanism for conveying client authorization data to
   authenticated servers. PACs are designed to be used with the DCE ACL
   facility.

   Whether the call actually wakes up in the server manager code or is
   rejected by the runtime depends on following conditions:

     +  If the client specified no authentication, then none is attempted
        by the RPC runtime.The call wakes up in the manager code whether
        the server specified authentication or not.  This permits both
        authenticated and unauthenticated clients to call authenticated
        servers.  When the manager receives an unauthenticated call, it
        needs to make a decision about how to proceed.

     +  If the client specified DCE secret key authentication and the
        server specified no authentication, then the runtime will fail
        the call, and it will never reach the manager routine.

     +  If both client and server specified DCE secret key
        authentication, then authentication will be carried out
        by the RPC runtime transparently.  Whether the call reaches
        the server manager code or is rejected by the runtime
        depends on whether the authentication succeeded.

   Although the RPC runtime is responsible any authentication that is
   carried out, the fact that the runtime will always permit
   unauthenticated clients to reach the manager code means that a
   manager access function typically does need to make an
   authentication check.  When the manager access routine calls
   rpc_binding_inq_auth_client() it needs to check for a status of
   rpc_s_binding_has_no_auth.  In this case, the client has specified
   no authentication and the manager access function needs to make an
   access decision based on this fact.  Note that in such a case, no
   meaningful authentication or authorization information is returned
   from rpc_binding_inq_auth_client().

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_binding_inq_auth_client
              rpc_binding_inq_auth_info
              rpc_mgmt_inq_dflt_protect_level
              rpc_mgmt_inq_server_princ_name
              sec_login_get_current_context
              sec_login_newgroups
              sec_login_setup_identity