2 — Universal User Library

[Previous] [Next] [Contents] [Index]

This chapter describes the Universal User Library (UUL). This chapter includes the following sections:

2.1 UUL Overview
2.3 context_ptr_type Definition
2.4 Interface Description
2.5 Error Codes

2.1 UUL Overview

The UUL is a collection of C function calls that allow a developer to convert a Distinguished Name (DN) or username and password into one of the following:

• Credentials handle for performing authorization checking

• Delegatable login context for making calls to Kerberos applications.

The following diagram shows the logical location of the UUL with respect to other server elements.

Figure 2-1: UUL Logical Relationships

The Security Adapter performs initial authentication and authorization checks and places information identifying the requesting user in the server's control structure. When the user program receives control, it calls the UUL to obtain the user's identity in the form of credentials handle or delegatable login context.

The UUL obtains the necessary credentials or login context for the user from the NetCrusader Security Server and returns them to the user program. The user program can then call the Authorization Library to perform authorization checking or make calls to Kerberos applications on behalf of the requesting user.

Notice that you use NetCrusader Commander to manage the ACL database for this particular server, as well as for managing user information in the NetCrusader Security Server.

2.2 How NetCrusader/Web Maps Identities

The NetCrusader/Web Security Adapter includes the Universal User Library (UUL) which is a library of function calls that can translate a DN or username/password to either of the following:

• Delegatable login context that can be used by a downstream application.

• Credentials handle that can be used for local authorization checking.

Figure 2-2 shows how and where mapping occurs within the NetCrusader/Web environment.

Figure 2-2: Identity Mapping

Here is how mapping occurs:

1. When the Security Adapter passes a request on for further server processing, it adds an Authorization header to the request that includes the user's DN. This makes the DN available for other filters and extensions.

2. A server extension extracts the DN from the request and calls a UUL function.

3. The UUL function requests the DN from the NetCrusader/Web Security Server, which contains a registry of NetCrusader identities and associated DNs.

   NOTE: Before an application can perform identity mapping, an administrator uses NetCrusader Commander to populate the NetCrusader Security Server registry with the required user entries. See the Commander online help for complete information on how to perform this task.

4. The NetCrusader Security Server returns the requested NetCrusader identity to the UUL call, which returns the identity to the calling extension.

The context_ptr parameter is an input for several UUL functions. The following table shows the context_ptr for the different values of context_ptr_type.

context_ptr_type	context_ptr
UUL_ISAPI_FILTER	HTTP_FILTER_CONTEXT* (defined by ISAPI)
UUL_ISAPI_EXTENSION	EXTENSION_CONTROL_BLOCK* (defined by ISAPI)
UUL_NSAPI_EXTENSION	Session * (defined by NSAPI)
UUL_NSAPI_PLUGIN	Obsolete A void pointer generated by a call to uul_nsapi_create_context().
UUL_NSAPI_FILTER	Reserved for internal use.
UUL_HTTP_AUTHORIZATION	Not supported for Version 3.1.2 for Windows NT char * pointing to a string containing the contents of the HTTP_AUTHORIZATION HTTP header from the request. You can obtain this string as follows: For ASP scripts, you can use: authhdr = Request.ServerVariables("HTTP_AUTHORIZATION") For CGI programs written in C or C++, you can use: authhdr = getenv("HTTP_AUTHORIZATION");

2.4 Interface Description

This section describes the functions that make up the UUL. Functions are listed in alphabetical order.

uul_free_context()
uul_free_credentials()
uul_get_credentials()
uul_get_delegation()
uul_get_principal()
uul_initialize()
uul_nsapi_create_context()
uul_terminate()

uul_free_context()

Frees the memory pointed to by the LoginContext.

Signature

unsigned long int    uul_free_context (
     uul_handle              handle,
     sec_login_handle_t*     LoginContext);

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_NO_ERROR
UUL_INVALID_CONTEXT_POINTER
UUL_CONTEXT_INVALID
UUL_INVALID_HANDLE

uul_free_credentials()

Frees the memory pointed to by the CredsPointer.

Signature

unsigned long int     uul_free_credentials(
     uul_handle          handle,
     uul_creds_ptr       CredsPointer);

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_INVALID_HANDLE
UUL_MEMORY_DELETION_ERROR
UUL_NO_ERROR

uul_get_credentials()

Gets a set of credentials handle for the user associated with the current session.

Signature

unsigned long int     uul_get_credentials (
     uul_handle          handle,
     int                 context_ptr_type,
     void *              context_ptr,
     uul_creds_ptr *     CredsPointer);

Use uul_get_credentials() to get a credentials handle for the user making a web request to access data. You can then check the user's permission to access the data by passing the credentials handle to the Authorization Library call authz_acl_authorized() (Page 36). You can also view the user's complete set of permissions to this object by passing the credentials handle to authz_acl_permissions() (Page 37). Once you are done with the credentials, free the memory allocated to them by calling uul_free_credentials() (Page 18).

Returns

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_ACCOUNT_INVALID
UUL_CONTEXT_INVALID
UUL_DIRECTORY_UNAVAILABLE
UUL_ERROR_ON_SERVER_VARIABLE
UUL_NO_ERROR
UUL_INVALID_CONTEXT_POINTER
UUL_INVALID_HANDLE
UUL_PASSWORD_INVALID
UUL_PASSWORD_NULL
UUL_PREAUTHENTICATION_FAILURE
UUL_MEMORY_DELETION_ERROR
UUL_NO_ENTRUST_FILTER
UUL_NO_MEMORY
UUL_UNKNOWN_ERROR
UUL_USER_DOES_NOT_EXIST

uul_get_delegation()

Gets a delegatable DCE login context for the user associated with the current session.

Signature

unsigned long int     uul_get_delegation (
     uul_handle              handle,
     int                     context_ptr_type,
     void *                  context_ptr,
     sec_login_handle_t *    DelegationCreds);

Use the uul_get_delegation() to get a delegatable login context for the user making a web request to access data. You can then make a call to a Kerberos application on behalf of this user.Once you are done with the context, free the memory allocated to them by calling uul_free_context() (Page 17).

When the UUL creates the login context, it includes the members of the Delegation Group as the list of allowed delegates. The net result is that the request cannot be accepted by a Kerberos application that does not appear in this list. You configure the name of the Delegation Group through the Security Adapter configuration program, which is described in the NetCrusader/Web Overview Guide. Use Commander to modify the group's contents (see the Commander online help for more information).

Returns

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_CONTEXT_INVALID
UUL_DIRECTORY_UNAVAILABLE
UUL_DN_DOES_NOT_EXIST
UUL_ERROR_ON_SERVER_VARIABLE
UUL_INVALID_HANDLE
UUL_MEMORY_DELETION_ERROR
UUL_NO_ENTRUST_FILTER
UUL_NO_ERROR
UUL_NO_MEMORY
UUL_UNKNOWN_ERROR
UUL_USER_DOES_NOT_EXIST

uul_get_principal()

Maps a set of user credentials to the corresponding principal name.

Signature

unsigned long int     uul_get_principal (
     uul_handle          handle,
     uul_creds_ptr       CredsPointer,
     char *              NameBuffer,
     int *               NameBufferLength);

First use uul_get_credentials() (Page 19) to get a credentials handle for the user making a web request to access data. You can then obtain the user's principal name by passing the credentials handle uul_get_principal().

If successful, NameBuffer contains the name of the principal associated with the credentials in CredsPointer, and NameBufferLength contains the length of the principal name (in bytes).

Returns

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_INVALID_CREDENTIALS
UUL_INVALID_HANDLE
UUL_NO_ERROR
UUL_STRING_INCOMPLETE

If this call returns UUL_STRING_INCOMPLETE, the buffer you supplied in NameBuffer was too small for the actual name. In this situation, the NameBuffer contains as much of the name as possible (NULL terminated), and NameBufferLength contains the size of the buffer required to retrieve the entire name.

uul_initialize()

Initializes the UUL. You must initialize the UUL before you can use it.

Signature

unsigned long int     uul_initialize (
     unsigned long int     Requested_Major_Revision
     unsigned long int     Requested_Minor_Revision,
     int                   context_ptr_type
     uul_handle *          uul_session_handle);

You initialize the UUL once per thread. You can initialize more than one session per program instance. You must terminate all sessions by calling uul_terminate() (Page 27) before the program shuts down.

The UUL is backwards compatible. If you request a version older than the current DLL, the call succeeds. However, if you request a version later than the current DLL, the call fails.

Returns

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_NO_ERROR
UUL_NO_MEMORY
UUL_REVISION_NOT_SUPPORTED

uul_nsapi_create_context()

NOTE: This function is supported only for backwards compatibility. For new applications, use UUL_NSAPI_EXTENSION as a context pointer type. For more information, see the discussion of the context_ptr_type in Section 2.3 on page 15.

Creates a context data structure for NSAPI that can be used by the uul_get_credentials() (Page 19) and uul_get_delegation() (Page 21) functions.

Signature

void * uul_nsapi_create_context (
     void *       SN
     void *       rq);

NSAPI server plug-ins use this call to create a context of UUL_NSAPI_PLUGIN type.

Returns

If successful, this call returns a void* pointer that you can pass to the uul_get_credentials() and uul_get_delegation() functions as a context pointer.

uul_terminate()

Ends this UUL session. You must call uul_terminate() to free resources used by the UUL.

Signature

unsigned long int     uul_terminate (
     uul_handle          uul_session_handle
     int                 context_ptr_type);

Returns one of the following error codes (for definitions, see Section 2.5 on page 28):

UUL_MEMORY_DELETION_ERROR
UUL_NO_ERROR

2.5 Error Codes

String	Number	Description
UUL_ACCOUNT_INVALID	5007	User's account is invalid.
UUL_CONTEXT_INVALID	5008	The specified context is invalid.
UUL_DIRECTORY_UNAVAILABLE	5002	The directory naming system is not currently available.
UUL_DN_DOES_NOT_EXIST	5014	The specified DN was not found in the registry.
UUL_ERROR_ON_SERVER_VARIABLE	5011	The UUL could not read a Server Variable (such as HTTP_AUTHENTICATION). Normally, this error means the user has authenticated with a method the UUL does not support.
UUL_INVALID_CONTEXT_POINTER	5012	Pointer does not point to a valid login context.
UUL_INVALID_CREDENTIALS	5018	Credentials structure passed in is not in a recognizable format, or the internal components were used in API calls that resulted in errors.
UUL_INVALID_HANDLE	5010	UUL handle specified is not valid.
UUL_MEMORY_DELETION_ERROR	5013	An error occurred attempting to release memory. Non-fatal. This error means the program will suffer some memory leakage problems.
UUL_NO_ENTRUST_FILTER	5016	An Entrust header was encountered but the Security Adapter is not loaded.
UUL_NO_ERROR	0	No errors occurred.
UUL_NO_MEMORY	5003	Insufficient memory to perform requested operation.
UUL_PASSWORD_INVALID	5005	The password supplied by the user is incorrect.
UUL_PASSWORD_NULL	5006	The user did not supply the requested password.
UUL_PREAUTHENTICATION_FAILURE	5009	An error occurred performing initial authentication.
UUL_REVISION_NOT_SUPPORTED	5017	Requested revision of the UUL is not supported.
UUL_STRING_INCOMPLETE	5019	The string being returned had to be truncated to fit the specified buffer.
UUL_UNKNOWN_ERROR	5004	Unexpected error has occurred.
UUL_USER_DOES_NOT_EXIST	5001	User you are attempting to login does not exist.

[Previous] [Next] [Contents] [Index]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 1997-2002 Entegrity Solutions Corporation & its subsidiaries