NAME

rpc_binding_inq_auth_info- returns authentication, authorisation and protection information from a server binding handle

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 information.

Input/Output

server_princ_name

Returns the server principal name referenced by 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.

Unless NULL is specified, the application should call the rpc_string_free() routine to free the storage used by this argument.

protect_level

Returns the protection level referenced by 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 referenced by binding. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Specifying NULL prevents the routine from returning this argument.

auth_identity

Returns a handle to a data structure that contains the client's authentication and authorisation credentials. This argument must be cast as appropriate for the authentication and authorisation services specified by authn_svc and authz_svc. (See Authentication, Authorisation and Protection-level Arguments for information about the appropriate data types appropriate to each service.)

Specifying NULL prevents the routine from returning this argument.

authz_svc

Returns the authorisation service referenced by binding. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Specifying NULL prevents the routine from returning this argument.

Output

status

Returns the status code from this routine. The 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_info() routine returns authentication, authorisation and protection-level information referenced by the server binding handle, binding. Client applications use this routine to discover whether the protection level they have requested is supported by the RPC run-time implementation.

A client application associates authentication, authorisation and protection-level information with a server binding handle by calling rpc_binding_set_auth_info(). The value of protect_level returned by rpc_binding_inq_auth_info() may be higher than the level requested in the previous call to rpc_binding_set_auth_info(). When an application requests a protection level that is not supported, the RPC run-time system attempts to upgrade the protection level to the next highest supported level. When it succeeds, the binding will be given a higher protection level than the one requested. Client applications may compare the requested protection level with the value returned by rpc_binding_inq_auth_info() to discover whether the requested protection level is actually supported by the run-time system.

The auth_identity argument points to the authentication and authorisation identity information associated with binding. rpc_binding_inq_auth_info() allocates no memory for this information, and references to auth_identity may not be valid after any subsequent call to rpc_binding_set_auth_info() with the same binding argument. In any case, the lifetime of auth_identity is no longer than the lifetime of binding.

Any of the data returned by rpc_binding_inq_auth_info() may be stale after a subsequent call to rpc_binding_set_auth_info() with the same binding argument.

The rpc_binding_inq_auth_info() routine allocates memory for the returned server_princ_name argument. The caller is responsible for calling the rpc_string_free() routine for the returned argument string.

RETURN VALUE

None.

SEE ALSO

rpc_binding_inq_auth_caller()
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.