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

Chapter 10
Additional APIs for Authenticated RPC

The following APIs are included in DCE Version 1.5 to create client credentials and to support server impersonation of a client. This means that the server runs with the security credentials of the client, and all of the capabilities of the client belong to the server. For additional information on RPC APIs, see the DCE Application Reference Manual and the DCE Administration Guide.

rpc_winnt_set_auth_identity

This function is called by the client RPC application to allocate and populate a WINNT auth_identity structure to be used as a parameter to rpc_binding_set_auth_info(). The caller must use the rpc_winnt_free_auth_identity() function to free the WINNT auth_identity. The strings that are passed in may be ASCII or Unicode (UCS-4) strings. The input flag will tell which type of strings they are.

Syntax


 #include <RPC.H>
          
 PUBLIC void rpc_winnt_set_auth_identity ( 
        rpc_winnt_auth_string_p_t        Username; 
        rpc_winnt_auth_string_p_t        Password; 
        rpc_winnt_auth_string_p_t        Domain; 
        unsigned __int64                 CharacterSetFlag; 
        rpc_auth_identity_handle_t       *auth_identity; 
        unsigned32                       *stp)

Arguments

INPUT

username --- Pointer to null terminated string containing username password --- Pointer to null terminated string containing password domain --- Pointer to null terminated string containing domain

CharacterSetFlag

SEC_WINNT_AUTH_IDENTITY_UNICODE --- 4 byte Unicode (UCS-4)
SEC_WINNT_AUTH_IDENTITY_ANSI --- ASCII (ISO8859-1)

OUTPUT

auth_identity --- Pointer to a pointer to a WINNT auth_identity structure stp --- Pointer to returned status

Note
Be sure to allocate space for three strings (username, password, domain). The string variables will probably be pointers of type unsigned_char_t if the strings are ASCII or pointers of type wchar_t if the strings are Unicode (UCS-4).

If the domain string is a valid empty string, then the domain of the computer will be used.

rpc_winnt_free_auth_identity

This function is called by the client RPC application to free a WINNT auth_identity structure that was previously allocated by a call to rpc_winnt_set_auth_identity().

Syntax


#include <RPC.H>
 
PUBLIC void rpc_winnt_free_auth_identity ( 
       rpc_auth_identity_handle_t  *auth_identity, 
       unsigned32                        *stp)

Arguments

INPUT

auth_identity --- Pointer to a pointer to a WINNT auth_identity structure. On output, auth_identity will be set to NULL.

OUTPUT

stp --- Pointer to returned status

Examples

The following code extract sets and frees the WINNT auth_identity. 


#include <dce/rpc.h> 
 
int main () 
{ 
/*                                              */ 
/* Declare variables to be used                 */ 
/*                                              */ 
 
rpc_auth_identity_handle_t      auth_identity; 
unsigned_char_t                 username[255]; 
unsigned_char_t                 domain[255]; 
unsigned_char_t                 password[255]; 
error_status_t                  status; 
 
 
/*                                              */ 
/* Initialize input arguments                   */ 
/*                                              */ 
 
printf("Enter username: "); 
gets(username); 
printf("Enter password: "); 
gets(password); 
printf("Enter domain: "); 
gets(domain); 
 
/*                                              */ 
/* Try to set the WINNT auth_identity           */ 
/* for use in rpc_binding_set_auth_info()       */ 
/*                                              */ 
 
rpc_winnt_set_auth_identity(username, password, domain, 
                            SEC_WINNT_AUTH_IDENTITY_ANSI, 
                            (rpc_auth_identity_handle_t*)&auth_identity, 
                             &status); 
 
if (status != rpc_s_ok) 
{ 
 printf ("*** Can't set winnt auth identity\n"); 
} 
else 
{ 
 rpc_winnt_free_auth_identity((rpc_auth_identity_handle_t*)&auth_identity, &status); 
} 
 
return(1); 
}

rpc_impersonate_client

This function is called by the server application to allow the current server thread to run with all of the client privileges.

Syntax


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

Arguments

INPUT

binding_handle --- Specifies a server-side call handle for this RPC which represents the client to impersonate.

OUTPUT

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

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 11
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_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

Previous Next Contents Index