NAME

rpc_binding_inq_auth_caller — Returns authentication and authorization information from the binding handle for an authenticated client;  used by server applications

Synopsis

void rpc_binding_inq_auth_caller(
rpc_binding_handle_t binding_handle,
rpc_authz_cred_handle_t ∗privs,
unsigned_char_p_t ∗server_princ_name,
unsigned32 ∗protect_level,
unsigned32 ∗authn_svc,
unsigned32 ∗authz_svc,
unsigned32 ∗status);

Parameters

Input

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

Output

privsReturns an opaque handle to the authorization information for the client that made the remote procedure call on binding_handle. 

The data referenced by this parameter are 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. 

server_princ_name
Returns a pointer to the server principal name specified by the client that made the remote procedure call on binding_handle.  The content of the returned name and its syntax are 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_svcReturns 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_svcReturns the authorization service requested by the client that made the remote procedure call on binding_handle. 

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 by using the client’s DCE privilege attribute certificate (PAC) sent to the server with each remote procedure call made with binding_handle.  Generally, access is checked against DCE access control lists (ACLs). 

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_ok
The routine completed successfully.

rpc_s_invalid_binding
The routine did not complete because of an invalid binding handle.

rpc_s_wrong_kind_of_binding
The routine did not complete because of the wrong kind of binding was specified for the operation.

rpc_s_binding_has_no_auth
The routine completed successfully, but the binding has no authentication information.

Description

The rpc_binding_inq_auth_caller() routine returns authentication and authorization information associated with the client identified by binding_handle.  The calling server manager routine can use the returned data for authorization purposes. 

If the client is part of a delegation chain, the call returns the authentication and authorization information for each member of the chain, the initiator and all subsequent delegates.  You can use the sec_cred_get_initiator() or sec_cred_get_delegate() calls to obtain the authorization information for a specific member of the chain. 

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 Interface Definition Language (IDL) auto_handle or implicit_handle attributes, 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_handle as the first parameter to each server manager routine. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

rpc_s_invalid_binding

rpc_s_wrong_kind_of_binding

rpc_s_binding_has_no_auth

sec_login_s_default_use

sec_login_s_context_invalid

error_status_ok

Related Information

Functions: rpc_binding_inq_auth_info(3rpc), rpc_binding_set_auth_info(3rpc), rpc_string_free(3rpc), sec_cred_get_initiator(3sec), sec_cred_get_delegate(3sec).