NAME

rpc_binding_inq_auth_caller- returns authentication, authorisation and protection information from the binding handle for an authenticated client

SYNOPSIS

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

void rpc_binding_inq_auth_caller(
	rpc_binding_handle_t binding,
	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

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

Input/Output

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 depend on the value of authn_svc. (See Authentication, Authorisation and Protection-level Arguments for authentication service-specific syntax.)

Specifying NULL prevents the routine from returning this argument. 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. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Specifying NULL prevents the routine from returning this argument.

authn_svc

Returns the authentication service requested by the client that made the remote procedure call on binding. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Specifying NULL prevents the routine from returning this argument.

authz_svc

Returns the authorisation service requested by the client that made the remote procedure call on binding_handle. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Specifying NULL prevents the routine from returning this argument.

Output

privs

Returns an opaque handle to the authorisation or privilege information for the client that made the remote procedure call on binding. The lifetime of the data referenced by this argument is one invocation of a server manager routine.

status

Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_binding_has_no_auth

Binding has no authentication information.

DESCRIPTION

The rpc_binding_inq_auth_caller() routine returns authentication, authorisation and privilege information referenced by the client binding handle, binding. The calling server manager routine can use the returned data for authorisation purposes.

Servers obtain client binding handles as the first argument of a remote procedure call. (See RPC Data Types and Introduction to the RPC API for more detailed information on how client binding handles are created and obtained.) The client binding handle references authentication, authorisation and privilege information for the client that made the remote procedure call.

A client establishes this information by calling rpc_binding_set_auth_info(), which associates a set of authentication, authorisation and privilege information with a server binding handle. When the client makes an RPC call on this server binding handle, the client binding handle received by the server references the same authentication, authorisation and privilege information.

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

No application memory is allocated for the data referenced by privs. The lifetime of this data is the current invocation of the manager routine that was called with the binding argument. An application that wishes to preserve any privileges information beyond this invocation must copy the information into application-allocated memory.

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 ACS explicit_handle attribute. Using explicit_handle provides binding as the first argument to each server manager routine.

SEE ALSO

rpc_binding_inq_auth_info()
rpc_binding_set_auth_info()
rpc_string_free().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.