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

bindingSpecifies the server binding handle for which to set the authentication and authorization information. 

server_princ_nameSpecifies 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_levelSpecifies 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.  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

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

rpc_c_protect_level_nonePerform no protection. 

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

rpc_c_protect_level_callPerform 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_pktEnsure that all data received is from the expected client. 

rpc_c_protect_level_pkt_integrity
Ensure and verify 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
Perform 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_svcSpecifies the authentication service to use.  The supported authentication services are

rpc_c_authn_noneNo authentication

rpc_c_authn_dce_secretDCE shared-secret key authentication

rpc_c_authn_dce_publicDCE public key authentication (reserved for future use)

rpc_c_authn_defaultDCE default authentication service

Specify rpc_c_authn_none to turn authentication off for remote procedure calls made using binding.  If rpc_c_authn_default is specified, the RPC runtime uses the rpc_c_authn_dce_secret authentication service for remote procedure calls made using binding. 

auth_identitySpecifies 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

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

authz_svcSpecifies 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

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

rpc_c_authz_nameServer performs authorization based on the client principal name. 

rpc_c_authz_dceServer 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). 

Output

statusReturns 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_okSuccess. 

rpc_s_invalid_bindingInvalid binding handle. 

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

rpc_s_unknown_authn_service
Unknown authentication service.

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, including authorization information. 

Unless a client calls this routine, all remote procedure calls made on the binding binding handle are unauthenticated.  A client is not required to call this routine. 

If a client is using the IDL auto_handle attribute and wants to perform authenticated RPC, it needs to call the stub support library routine rpc_ss_register_auth_info.  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. 

NOTES

For this release, the RPC authentication (RPC auth) routines are not implemented, nor is an independent security service provided. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_binding_inq_auth_info(3), rpc_mgmt_inq_dflt_protect_level(3), rpc_mgmt_inq_server_princ_name(3), rpc_ss_register_auth_info(3)