Document revision date: 5 July 2000
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Compaq DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide
Previous Contents Index

rpc_revert_to_self

This function is called by the server application to revert back to its original security context after impersonating a client.

Syntax


#include <RPC.H>
 
       rpc_revert_to_self(*status)

Arguments

INPUT

None.

OUTPUT

status --- Specifies a pointer to an unsigned 32-bit integer that holds a status code.

rpc_revert_to_self_ex

This function is called by the server to revert back to its original security context after impersonating a client. This acts as a call to rpc_revert_to_self();

Syntax


#include <RPC.H>
 
       rpc_revert_to_self_ex( 
       rpc_binding_handle_t        binding_handle, 
       rpc_status_t                *status)

Arguments

INPUT

call handle --- This parameter is ignored.

OUTPUT

status --- Specifies a pointer to an unsigned 32-bit integer that holds a status code.

Chapter 9
Enhancements to Existing Authenticated RPC APIs

rpc_binding_set_auth_info

This function sets authentication and authorization information for a server binding handle. It is used by client applications.

Syntax


#include <dce/rpc.h> 
#include <dce/sec_login.h> 
 
void rpc_binding_set_auth_info( 
        rpc_binding_handle_t binding, 
        unsigned_char_t *server_princ_name, 
        unsigned32 protect_level, 
        unsigned32 authn_svc, 
        rpc_auth_identity_handle_t auth_identity, 
        unsigned32 authz_svc, 
        unsigned32 *status);

Arguments

INPUT

binding

Specifies the server binding handle to set the authentication and authorization information.

server_princ_name

Specifies the principal name of the server referenced by binding. The content of the name and its syntax is defined by the authentication service in use.

A client that does not know the server principal name but wishes to know it, can call the rpc_mgmt_inq_server_princ_name() routine to obtain the principal name of a server that is registered for the required authentication service. Using a principal name obtained in this way means that the client is interested in one-way authentication. In other words, it means that the client does not care which server principal received the remote procedure call request. The server, though, still verifies that the client is who the client claims to be.

protect_level

Specifies the protection level for remote procedure calls made using binding. The protection level determines the degree to which authenticated communications between the client and the server are protected by the authentication service specified by authn_svc.

If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level. The possible protection levels are as follows:

authn_svc

Specifies the authentication service to use. The exact level of protection provided by the authentication service is specified by the protect_level parameter. The supported authentication services are as follows:

auth_identity

Specifies a handle for the data structure that contains the client's authentication and authorization credentials appropriate for the selected authentication and authorization services.

When using the rpc_c_authn_dce_secret authentication service and any authorization service, this value must be a sec_login_handle_t obtained from one of the following routines:

These routines are described in the DCE Application Development Guide.

Specify NULL to use the default security login context for the current address space.

When using the rpc_c_authn_winnt authentication service, this value must be a rpc_auth_identity_handle_t obtained from the rpc_winnt_set_auth_identity() routine.

Specify NULL to use the default security login context for the current address space.

authz_svc

Specifies the authorization service implemented by the server for the interface of interest. The validity and trustworthiness of authorization data, like any application data, is dependent on the authentication service and protection level specified. The supported authorization services are as follows:

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:

Description

The rpc_binding_set_auth_info() routine sets up the specified server binding handle so that it can be used to make authenticated remote procedure calls that include authorization information.

Unless a client calls rpc_binding_set_auth_info() with the parameters to set establish authentication and authorization methods, all remote procedure calls made on the binding binding handle are unauthenticated. Some authentication services (authn_svc) may need to communicate with the Security service to perform this operation. Otherwise, they may receive the rpc_s_comm_failure status.

The authn_svc parameter specifies the authentication service to use. If authentication is chosen, the protect_level parameter can specify a variety of protection levels, ranging from no authentication to the highest level of authentication and encryption. If the protect_level parameter is set to rpc_c_protect_level_none, no authentication is performed, regardless of the authentication service chosen.

If the authn_svc parameter is WINNT and the protect_level parameter is set to rpc_c_protect_level_none, no authentication information will be set on the binding. This means that calls to rpc_binding_inq_auth_info() will fail with the rpc_s_binding_has_no_auth status.

The authz_svc parameter specifies the authorization service to use. If no authentication has been chosen (authn_svc of rpc_c_authn_none), then no authorization (authz_svc of rpc_c_authz_none) must be chosen as well. If authentication will be performed, and the authn_svc is rpc_c_authn_dce_secret you have two choices for authorization: name-based authorization and DCE authorization. The use of name-based authorization, which provides a server with a client's principal name, is not recommended. DCE authorization uses PACs, a trusted mechanism for conveying client authorization data to authenticated servers. PACs are designed to be used with the DCE ACL facility. If authentication will be performed, and the authn_svc is rpc_c_authn_winnt you have one choice for authorization: rpc_c_authz_none.

The server_princ_name parameter specifies the principal name of the server referenced by binding. If the server_princ_name parameter is NULL, the RPC runtime will call the rpc_mgmt_inq_server_princ_name() routine on the users behalf. The resulting server principal name will get stored in the binding for future use by the client application if desired. The designer of the client application needs to decide if this is the desired behavior. Some authentication services such as rpc_c_authn_dce_secret needs the server’s principal name for a successful authentication. The rpc_c_authn_winnt authentication service has no dependency on the server's principal name for a successful authentication. If the client application has no need to know the server's principal name and would not like to incur the overhead of automatically obtaining it, then the server_princ_name parameter should be non-null.

Whether the call actually wakes up in the server manager code or is rejected by the runtime depends on following conditions:

Although the RPC runtime is responsible any authentication that is carried out, the fact that the runtime will always permit unauthenticated clients to reach the manager code means that a manager access function typically does need to make an authentication check. When the manager access routine calls rpc_binding_inq_auth_client() it needs to check for a status of rpc_s_binding_has_no_auth. In this case, the client has specified no authentication and the manager access function needs to make an access decision based on this fact. Note that in such a case, no meaningful authentication or authorization information is returned from rpc_binding_inq_auth_client().

Return Values

No value is returned.

See Also

rpc_binding_inq_auth_client(3rpc)
rpc_binding_inq_auth_info(3rpc)
rpc_mgmt_inq_dflt_protect_level(3rpc)
rpc_mgmt_inq_server_princ_name(3rpc)
sec_login_get_current_context(3sec)
sec_login_newgroups(3sec)
sec_login_setup_identity(3sec)
rpc_winnt_set_auth_identity
rpc_winnt_free_auth_identity

rpc_binding_inq_auth_info

Returns authentication and authorization information from a server binding handle. It is used by client applications.

Syntax


#include <dce/rpc.h> 
#include <dce/sec_login.h> 
 
void rpc_binding_inq_auth_info( 
        rpc_binding_handle_t binding, 
        unsigned_char_t **server_princ_name, 
        unsigned32 *protect_level, 
        unsigned32 *authn_svc, 
        rpc_auth_identity_handle_t *auth_identity, 
        unsigned32 *authz_svc, 
        unsigned32 *status);

Arguments

INPUT

binding

Specifies the server binding handle from which to return the authentication and authorization information.

OUTPUT

server_princ_name

Returns a pointer to the expected principal name of the server referenced by binding. The content of the returned name and its syntax is defined by the authentication service in use.

Specifying NULL prevents the routine from returning this parameter. In this case, the caller does not have to call the rpc_string_free() routine.

protect_level

Returns the protection level used for remote procedure calls made with binding. The protection level determines the degree to which authenticated communications between the client and the server are protected.

Note that the returned level may be different from the level specified for protect_level on the call to rpc_binding_set_auth_info(). If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level.

Specifying NULL prevents the routine from returning this parameter. The possible protection levels are as follows:

authn_svc

Returns the authentication service used for remote procedure calls made with binding. Specifying NULL prevents the routine from returning this argument.

The possible authentication services are as follows:

auth_identity

Returns a handle for the data structure that contains the client's authentication and authorization credentials. This parameter must be cast as appropriate for the authentication and authorization services established via rpc_binding_set_auth_info().

When using the rpc_c_authn_dce_secret authentication service and any authorization service, this value must be a sec_login_handle_t obtained from one of the following routines:

These routines are described in the DCE Application Development Guide.

Specifying NULL prevents the routine from returning this parameter. When using the rpc_c_authn_winnt authentication service, this value must be a rpc_auth_identity_handle_t obtained from the rpc_winnt_set_auth_identity() routine. Specify NULL prevents the routine from returning this parameter.

authz_svc

Returns the authorization service used for remote procedure calls made with binding.

Specifying NULL prevents the routine from returning this parameter. The possible authorization services are as follows:

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:

Description

The rpc_binding_inq_auth_info() routine returns authentication and authorization information associated with the specified server binding handle. The calling client associates the authentication and authorization data with the server binding handle by a prior call to the rpc_binding_set_auth_info() routine.

The RPC runtime allocates memory for the returned server_princ_name parameter. The caller is responsible for calling the rpc_string_free() routine for the returned parameter string.

Return Values

No value is returned.

See Also

rpc_binding_set_auth_info(3rpc)
rpc_string_free(3rpc)

rpc_server_register_auth_info

This routine registers authentication information with the RPC runtime. It is used by server applications.

Syntax


#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);

Arguments

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:

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, /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 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:

Description

The rpc_server_register_auth_info() routine registers an authentication 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. Also note that if authn_svc is rpc_c_authn_winnt, 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.
rpc_c_authn_winnt NULL Ignored Uses the default method of encryption key acquisition from the default key table.
rpc_c_authn_winnt non-NULL Ignored Error returned.

Return Values

No value is returned.

See Also

rpc_binding_set_auth_info(3rpc)

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6533_DCE_REF_PRO_009.HTML