RpcServerRegisterAuthInfo

The RpcServerRegisterAuthInfo function registers authentication information with the RPC run-time library.

This function is supported by both 32-bit platforms — Windows NT and Windows 95.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcServerRegisterAuthInfo( 
  unsigned char *  ServerPrincName,   
  unsigned long  AuthnSvc,            
  RPC_AUTH_KEY_RETRIEVAL_FN  GetKeyFn,   
  void *  Arg                         
);
 

Parameters

ServerPrincName
Points to the principal name to use for the server when authenticating remote procedure calls using the service specified by the AuthnSvc argument. The content of the name and its syntax are defined by the authentication service in use.
AuthnSvc
Specifies an authentication service to use when the server receives a request for a remote procedure call.
GetKeyFn
Specifies the address of a server-application-provided routine that returns encryption keys.

Specify a NULL argument value to use the default method of encryption-key acquisition. In this case, the authentication service specifies the default behavior. Set this parameter to NULL when using the RPC_C_AUTHN_WINNT authentication service.
Authentication service GetKeyFn Arg Run-time behavior
RPC_C_AUTHN_DCE
_PRIVATE
NULL Non-null Uses default method of encryption-key acquisition from specified key table; specified argument is passed to default acquisition function
RPC_C_AUTHN_DCE
_PRIVATE
Non-null NULL Uses specified encryption-key acquisition function to obtain keys from default key table
RPC_C_AUTHN_DCE
_PRIVATE
Non-null Non-null Uses specified encryption-key acquisition function to obtain keys from specified key table; specified argument is passed to acquisition function
RPC_C_AUTHN_DEC
_PUBLIC
Ignored Ignored Reserved for future use
RPC_C_AUTHN_WINNT Ignored Ignored Does not support

The following C-language definition for RPC_AUTH_KEY_RETRIEVAL_FN illustrates the prototype for RpcServerRegisterAuthInfo:

typedef void (* RPC_AUTH_KEY_RETRIEVAL_FN)(
    void * arg, /* in */
    unsigned char * ServerPrincName, /* in */
    unsigned int key_ver, /* in */
    void * * key, /* out */
    unsigned int * status /* out */);
 

The RPC run-time library passes the ServerPrincName argument value from RpcServerRegisterAuthInfo as the ServerPrincName argument value to the GetKeyFn acquisition function.

The RPC run-time library automatically provides a value for the key version (KeyVer) argument. For a KeyVer argument value of zero, the acquisition function must return the most recent key available.

The retrieval function returns the authentication key in the Key argument.

If the acquisition function called from RpcServerRegisterAuthInfo returns a status other than RPC_S_OK, RpcServerRegisterAuthInfo fails and returns an error code to the server application.

If the acquisition function called by the RPC run-time library while authenticating a client's remote procedure call request returns a status other than RPC_S_OK, the request fails and the RPC run-time library returns an error code to the client application.

Arg
Points to an argument to pass to the GetKeyFn routine, if specified.

Remarks

A server application calls the RpcServerRegisterAuthInfo routine to register an authentication service to use for authenticating remote procedure calls. A server calls this routine once for each authentication service and/or principal name the server wants to register.

The authentication service specified by a client application (using RpcBindingSetAuthInfo or RpcServerRegisterAuthInfo) must be one of the authentication services specified by the server application. Otherwise, the client's remote procedure call fails and an RPC_S_UNKNOWN_AUTHN_SERVICE status code is returned.

Return Values

Value Meaning
RPC_S_OK Success
RPC_S_UNKNOWN_AUTHN_SERVICE Unknown authentication service

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcdce.h.
  Import Library: Link with rpcrt4.lib.

See Also

RpcBindingSetAuthInfo