rpc_server_register_auth_info- registers authentication information with the RPC run-time system
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);
- Specifies a server principal name to use when authenticating remote procedure calls using the service specified by authn_svc. The content and syntax of the name depend on the value of authn_svc. (See
Authentication, Authorisation and Protection-level Argumentsfor authentication service specific syntax.)
- Specifies the authentication service to use when the server receives a remote procedure call request. (See
Authentication, Authorisation and Protection-level Argumentsfor the possible values of this argument.)
- Specifies the address of a server application-provided routine that returns keys suitable for the specified authn_svc.
To use the authentication service-specific default method of acquiring keys, NULL may be specified for this argument. (See
Authentication, Authorisation and Protection-level Argumentsfor a description of the authentication service-specific run-time behaviour for acquiring keys.)
The following C definition for rpc_auth_key_retrieval_fn_t illustrates the prototype for the key acquisition routine:
typedef void (*rpc_auth_key_retrieval_fn_t) ( void *arg, /* in */ unsigned_char_t *server_princ_name, /* in */ unsigned32 key_ver, /* in */ void **key, /* out */ unsigned32 *status /* out */ );
The RPC run-time system passes the server_princ_name argument value for rpc_server_register_auth_info(), as the server_princ_name argument value for the get_key_fn key acquisition routine. The RPC run-time system automatically supplies a value for the key_ver argument.
The implementation of the key acquisition routine depends on the authentication service in use. The routine must return a key appropriate to the authentication service in the get_key_fn argument. For a key_ver value of 0 (zero), the key acquisition routine must return the most recent key available, as defined by the authentication service.
The key acquisition routine may be called from rpc_server_register_auth_info(). In this case, if the key acquisition 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.
The key acquisition routine is called by the run-time system while authenticating remote procedure call requests. If it returns a status other than rpc_s_ok, the request fails and the run-time system returns the error status to the calling client.
- Specifies an argument to pass to the key acquisition routine. (See
Authentication, Authorisation and Protection-level Argumentsfor an explanation of how this argument is treated by the run-time system, depending on the value of authn_svc and get_key_fn.)
- Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.
Possible status codes and their meanings include:
Unknown authentication service.
Servers call the rpc_server_register_auth_info() routine to register an authentication service to use for authenticating remote procedure calls. A server calls this routine once for each authentication service-principal name combination that it wants to register. Severs can register a non-default key acquisition function and a key acquisition function argument when calling rpc_server_register_auth_info().
Applications may make multiple calls to rpc_server_register_auth_info() to register several principal name-authentication service combinations. When an application calls rpc_server_register_auth_info() with a combination already registered, the new registration overwrites the old one.
A client application makes authenticated remote procedure calls using a binding annotated with authentication information. If the binding has not been annotated with one of the principal name-authentication service combinations registered by the server, the client's remote procedure call request may be rejected by the manager routine.
Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.