NAME

rpc_server_register_auth_info- registers authentication information with the RPC run-time system

SYNOPSIS

#include <dce/rpc.h>

void rpc_server_register_auth_info(
	unsigned_char_t *server_princ_name,
	unsigned32 authn_svc,
	rpc_auth_key_retrieval_fn_t get_key_fn,
	void *arg,
	unsigned32 *status);

PARAMETERS

Input

server_princ_name

Specifies a server principal name to use when authenticating remote procedure calls using the service specified by authn_svc. The content and syntax of the name depend on the value of authn_svc. (See Authentication, Authorisation and Protection-level Arguments for authentication service specific syntax.)

authn_svc

Specifies the authentication service to use when the server receives a remote procedure call request. (See Authentication, Authorisation and Protection-level Arguments for the possible values of this argument.)

get_key_fn

Specifies the address of a server application-provided routine that returns keys suitable for the specified authn_svc.

To use the authentication service-specific default method of acquiring keys, NULL may be specified for this argument. (See Authentication, Authorisation and Protection-level Arguments for a description of the authentication service-specific run-time behaviour for acquiring keys.)

The following C definition for rpc_auth_key_retrieval_fn_t illustrates the prototype for the key acquisition routine:

typedef void (*rpc_auth_key_retrieval_fn_t)
 (
  void            *arg,               /* in */
  unsigned_char_t *server_princ_name, /* in */
  unsigned32      key_ver,            /* in */
  void            **key,              /* out */
  unsigned32      *status             /* out */
 );

The RPC run-time system passes the server_princ_name argument value for rpc_server_register_auth_info(), as the server_princ_name argument value for the get_key_fn key acquisition routine. The RPC run-time system automatically supplies a value for the key_ver argument.

The implementation of the key acquisition routine depends on the authentication service in use. The routine must return a key appropriate to the authentication service in the get_key_fn argument. For a key_ver value of 0 (zero), the key acquisition routine must return the most recent key available, as defined by the authentication service.

The key acquisition routine may be called from rpc_server_register_auth_info(). In this case, if the key acquisition routine returns a status other than rpc_s_ok, the rpc_server_register_auth_info() routine fails and returns the error status to the calling server.

The key acquisition routine is called by the run-time system while authenticating remote procedure call requests. If it returns a status other than rpc_s_ok, the request fails and the run-time system returns the error status to the calling client.

arg

Specifies an argument to pass to the key acquisition routine. (See Authentication, Authorisation and Protection-level Arguments for an explanation of how this argument is treated by the run-time system, depending on the value of authn_svc and get_key_fn.)

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_unknown_authn_service

Unknown authentication service.

DESCRIPTION

Servers call the rpc_server_register_auth_info() routine to register an authentication service to use for authenticating remote procedure calls. A server calls this routine once for each authentication service-principal name combination that it wants to register. Severs can register a non-default key acquisition function and a key acquisition function argument when calling rpc_server_register_auth_info().

Applications may make multiple calls to rpc_server_register_auth_info() to register several principal name-authentication service combinations. When an application calls rpc_server_register_auth_info() with a combination already registered, the new registration overwrites the old one.

A client application makes authenticated remote procedure calls using a binding annotated with authentication information. If the binding has not been annotated with one of the principal name-authentication service combinations registered by the server, the client's remote procedure call request may be rejected by the manager routine.

RETURN VALUE

None.

SEE ALSO

rpc_binding_set_auth_info()
rpc_server_register_auth_info().

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.