NAME

rpc_server_register_auth_info — Registers server-key based authentication information with the RPC runtime;  used by server applications

Synopsis

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 nam e 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 following authentication services are supported:

rpc_c_authn_none
No authentication.

rpc_c_authn_dce_secret
DCE shared-secret key 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_ret rieval_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. 

Note:

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. 

argSpecifies 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, /krb/v5srvtab.  The calling server must be root to access this file. 

If arg is a key table filename, the file must have been created with the ktadd command.  If the specified key table file resides in /krb5, you can supply only the filename.  If the file does not reside in /krb5, you must supply the full pathname.  You must prepend the file’s absolute pathname with the prefix FILE:. 

Output

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not. 

Description

The rpc_server_register_auth_info() routine registers an authentication service to use for authenticating remote procedure calls to a particular server principal. This routine is used for server-key based authentication.  Use the rpc_server_register_auth_ident() routine for user-to-user authentication. 

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. 

Return Values

No value is returned. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

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 nonnull value was supplied for get_key_fn parameter. 

Related Information

Functions: rpc_binding_set_auth_info(3rpc), rpc_server_register_auth_ident(3rpc).