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 |
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 |
Non-null |
NULL |
Uses
specified encryption-key acquisition function to obtain keys from default key
table |
|
RPC_C_AUTHN_DCE |
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 |
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 |
See Also