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_name
Specifies 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_svc
Specifies the authentication service to use when the server
receives a remote procedure call request. The following
authentication services are supported:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_winnt
Microsoft NT Lan Manager authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_default
DCE default authentication service.
get_key_fn
Specifies the address of a server-provided routine that returns
encryption keys.
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_type, /* in */
unsigned32 key_ver, /* in */
void **key, /* out */
unsigned32 *status /* out */
);
The RPC runtime passes the server_princ_name parameter value
specified on the call to rpc_server_register_auth_info(), as
the server_princ_name parameter value, to the get_key_fn key
acquisition routine. The RPC runtime automatically provides a
value for the key version (key_ver) parameter. 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 parameter. The key_type parameter specifies a Kerberos
encryption key type. Because currently the DCE supports only
DES encryption, this parameter can be ignored.
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.
arg Specifies an argument to pass to the get_key_fn key acquisition
routine, if specified. (See the description of the get_key_fn
parameter for details.)
Specify NULL for arg to use the default key table file,
DCE$LOCAL:[KRB]v5srvtab.;
The calling server must be privileged to access this file.
If arg is a key table file name, the file must have been
created with the ktadd command. If the specified key table
file resides in DCE$LOCAL:[KRB5], you can supply only the file
name. If the file does not reside in DCE$LOCAL:[KRB5], you must
supply the full pathname. You must prepend the file's absolute
pathname with the prefix FILE:.
Output
status
Returns 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_ok Success.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_key_func_not_allowed
authn_svc is rpc_c_authn_default and a non-null
value was supplied for get_key_fn parameter.
DESCRIPTION
The rpc_server_register_auth_info() routine registers an authenti-
cation 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 the
rpc_binding_set_auth_info() routine) must be one of the authentication
services registered by the server. If it is not, the client's remote
procedure call request fails with an rpc_s_unknown_authn_service
status code.
The following table shows the RPC runtime behavior for acquiring
encryption keys for each supported authentication service. Note that
if authn_svc is rpc_c_authn_default, then get_key_fn must be NULL.
RPC Key Acquisition for Authentication Services
_______________________________________________________________________
authn_svc get_key_fn arg Runtime Behavior
_______________________________________________________________________
rpc_c_authn_default NULL NULL Uses the default method of
encryption key acquisition
from the default key
table.
_______________________________________________________________________
rpc_c_authn_default NULL non-NULL Uses the default method of
encryption key acquisition
from the specified key
table.
_______________________________________________________________________
rpc_c_authn_default non-NULL Ignored Error returned.
_______________________________________________________________________
rpc_c_authn_none Ignored Ignored No authentication
performed.
_______________________________________________________________________
rpc_c_authn_dce_secret NULL NULL Uses the default method of
encryption key acquisition
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_secret NULL non-NULL Uses the default method of
encryption key acquisition
from the specified key
table.
_______________________________________________________________________
rpc_c_authn_dce_secret non-NULL NULL Uses the specified encryp-
tion key acquisition
routine to obtain keys
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_secret non-NULL non-NULL Uses the specified encryp-
tion key acquisition
routine to obtain keys from
the specified key table.
_______________________________________________________________________
rpc_c_authn_winnt Ignored Ignored Uses the default method of
encryption key acquisition
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_public Ignored Ignored (Reserved for future use.)
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_set_auth_info