NAME

rpc_server_register_auth_info - Registers authentication information with the RPC runtime

Used by server applications. 

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_nameSpecifies the principal name to use for the server when authenticating remote procedure calls using the service specified by authn_svc.  The content of the name and its syntax is defined by the authentication service in use. 

authn_svcSpecifies the authentication service to use when the server receives a remote procedure call request.  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

get_key_fnSpecifies the address of a server-provided routine that returns encryption keys.  Specifying NULL uses the default method of acquiring encryption keys.  In this case, authn_svc must specify rpc_c_authn_default.  The following table shows the RPC runtime behavior for acquiring encryption keys for each supported authentication service:

Table 0-0.  RPC Key Acquisition for Authentication Services

The following C definition for rpc_auth_key_retrieval_fn_t illustrates the prototype for the encryption 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 runtime passes the server_princ_name argument value specified on the call to rpc_server_register_auth_info, as the server_princ_name argument value, to the get_key_fn key acquisition routine.  The RPC runtime automatically provides a value for the key version (key_ver) argument.  For a key_ver value of 0 (zero), the key acquisition routine must return the most recent key available.  The routine returns the key in the key argument.  If the key acquisition routine, when called from the rpc_server_register_auth_info 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.  If the key acquisition routine, when called by the RPC runtime while authenticating a client remote procedure call request, returns a status other than rpc_s_ok, the request fails and the RPC runtime returns the error status to the client. 

argSpecifies an argument to pass to the get_key_fn key acquisition routine, if specified.  See the description of the get_key_fn argument for details. 

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_unknown_authn_service
Unknown authentication service.

DESCRIPTION

The rpc_server_register_auth_info routine registers an authentication service to use for authenticating remote procedure calls to a particular server principal.  A server calls this routine once for each authentication service and principal name combination that it wants to register. 

The authentication service specified by a client (using rpc_binding_set_auth_info or rpc_ss_register_auth_info) must be one of the authentication services registered by the server.  If it is not, the client’s remote procedure call request fails with a rpc_s_unknown_authn_service status code. 

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_set_auth_info(3), rpc_ss_register_auth_info(3)