rpc_server_register_auth_info(3rpc)
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_dce_public | DCE public key authentication (reserved for future use). |
| rpc_c_authn_default | DCE default authentication service. |
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.
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.
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, /krb/v5srvtab. The calling server must be root 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 /krb5, you can supply only the file name. If the file does not reside in /krb5, you must supply the full path name. You must prepend the file's absolute path name 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.
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.
| 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 encryption key acquisition routine to obtain keys from the default key table. |
| rpc_c_authn_dce_secret | non-NULL | non-NULL | Uses the specified encryption key acquisition routine to obtain keys from the specified key table. |
| rpc_c_authn_dce_public | Ignored | Ignored | (Reserved for future use.) |
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 non-null value was supplied for get_key_fn parameter.
Related Information
Functions: rpc_binding_set_auth_info(3rpc)
rpc_server_register_auth_ident(3rpc)