VMS Authentication Module Administration & User's Guide

Chapter 4 Using the VAM API

Introduction

VAM provides an API for allowing user-written applications to use SecurID or local UAF authentication for controlling access to the application. This can be implemented by a business that uses normal operating-system access for its internal functions, but which may need further authentication for specific applications that interface to counterparts on remote systems. In this case, VAM provides an additional layer of security for access to that application.

This chapter describes how to use the VAM API when using VAM as a front-end for an application.

Compiling a VAM Application

When compiling a source module that will call the VMSAuthenticate function, include the file VAM:VMSAUTHENTICATE.H.

Linking A VAM Application

To link an application which uses the VAM API, include the file VAM:[VAM]VAM_LINK.OPT. For example:

$ LINK MYAPPLICATION,VAM:[VAM]VAM_LINK.OPT/OPTION

VAM API Functions

The following sections describe each of the VAM API calls. It includes not only the VMSAuthenticate function, but also the callback functions that are supplied by the user.

VMSAuthenticate

The user application calls VMSAuthenticate to perform authentication. VMSAuthenticate must be supplied with an identifier that defines what type of authentication will take place and a username. A password may be supplied; however, it may be ignored (for example, in the case of performing SecurID authentication). The application must provide four callbacks to interact with the user.

VMSAuthenticate is a synchronous function; as such, it will not return until authentication completes successfully or fails.

Format

int VMSAuthenticate {

char * AuthenticationType,

char * Username,

char * Password,

int * (*IOCallback)(),

int * (*InfoCallback)(),

void * (*TimeoutCallback)(),

void * (*ScreenClearCallback)(),

int * UserData,

char * Identifier,

0, 0

);

Inputs

• AuthenticationType - String (null-terminated) containing the type of authentication desired. Currently, must be "SECURID" or "LOCALUAF".

• Username - String (null-terminated) containing the username to be checked. The username is case-sensitive, and must match the case of the username when entered at the SecurID server.

• Password - String (null-terminated) containing the password to be checked. Ignored when AuthenticationType is "SECURID". Required when AuthenticationType is "LOCALUAF".

• IOCallback - Pointer to the user-defined callback to be called when a prompt/response dialog must be performed with the user.

• InfoCallback - Pointer to the user-defined callback to be called when an informational message must be displayed to the user.

• TimeoutCallback - Pointer to the user-defined callback to be called when a prompt timeout occurs.

• ScreenClearCallback - Pointer to the user-defined callback to be called when the screen is to be cleared after a prompt.

• UserData - Pointer to a user-defined data area. The contents and size of this data area are to be defined by the user, and may contain any context information desired by the user (for example, to identify the user or terminal being authenticated). This pointer will be passed to all user-defined callback routines.

• Identifier - String (null-terminated) that contains the name of the application. This will be used to match a VMS rights identifier when AuthenticationType is " LOCALUAF". If this field is not specified for LOCALUAF processing, the identifier VAM_UAF_ID is used by default. This field is ignored for SECURID processing.

Note! The final two parameters (denoted by "0, 0" above) are reserved for future use but must be specified.

Outputs

None.

Returns

SS$_NORMAL

Authentication successful.

SS$_ABORT

Authentication was aborted by the server

SS$_BADPARAM

• No username was supplied

• Authentication type was not "SECURID" or "LOCALUAF"

• All callbacks were not supplied

SS$_CANCEL

• Authentication was aborted by the user

SS$_NOLICENSE

A valid license was not loaded.

Note! When performing authentication, the return status will never tell the user program (provided the arguments to the routine call were correct) why the authentication failed, only that it did fail. Providing this information to a user could provide an attacker with a clue as to what to try next.

IOCallback

This user-application-supplied routine is called when a prompt/response dialog (consisting of exactly one prompt and expecting exactly one response) must be conducted with the user. The callback will be called with the information necessary to prompt for and return the required information (for example, the prompt to use, the length characteristics of the expected response, and if the response should be echoed to the terminal screen). The callback is expected to prompt for the data and return the null-terminated data in the response field. The callback is responsible (when directed by the EchoFlag) for turning echo to the terminal off before prompting for the data, and turning echo back on after getting the data from the caller.

In the case of performing SecurID authentication, the callback routine may perform any necessary editing to ensure the format & type of the data is correct (for example, to ensure it doesn't exceed the maximum length and is of the correct - numeric or alphanumeric - type). However, this isn't required, as the VMSauthenticate routine will also perform these checks on behalf of the user. The benefit of the user program performing these checks may lie in providing the ability to instantly provide feedback to the user in the event the response violates the input parameters.

Format

int IOCallback(

char * Prompt,

char * Response,

int MinRespLen,

int MaxRespLen,

int RespType,

int EchoFlag,

int Timeout,

int * UserData

);

Inputs

• Prompt - String (null-terminated) that contains the prompt to display.

• MinRespLen - Minimum length of expected response.

• MaxRespLen - Maximum length of expected response.

• RespType - Type of data desired for the expected response, where 0 = numeric (0-9) and 1 = alphanumeric.

• EchoFlag - Set to 1 if the response should be echoed to the screen.

• Timeout - Time (in seconds) to display the prompt.

Outputs

• Response - character string (null-terminated) that contains the response returned by the user.

Returns

1 = successfully completed

0 = call was aborted. This will cause the authentication session to be terminated, with VMSAuthenticate returning a status of SS$_CANCEL.

InfoCallback

This user application-supplied callback routine is used when an informational message must be displayed by the user application with no response required (save for possibly an "OK" button in, for example, a DECwindows application).

Format

int InfoCallback(

char * Prompt,

int Timeout,

Int * UserData

);

Inputs

• Prompt - Character string (null-terminated) that contains the prompt to display.

• Timeout - Time (in seconds) to display the prompt

Outputs

None.

Returns

1 = successfully completed

0 = call was aborted. This will cause the authentication session to be terminated, with VMSAuthenticate() returning a status of SS$_CANCEL.

TimeoutCallback

This user application-supplied callback routine is invoked when a timeout for a prompt has been exceeded. The user application is required to terminate the I/O operation that it invoked. This timer is started just prior to calling the user-supplied IOCallback or InfoCallback routines, and the RSA Authentication Manager supplies its value.

Note! The user program must not disable AST's via the VMS $SETAST system service. If this is done, timeouts won't be enforced.

Format

void TimeoutCallback(

int * UserData

);

Inputs

UserData - Pointer to a user-defined data area. The contents and size of this data area are to be defined by the user, and may contain any context information desired by the user (for example, to identify the user or terminal being authenticated)..

Outputs

None.

Returns

None.

ScreenClearCallback

This user application-supplied callback routine is used when the screen should be cleared subsequent to a call to IOCallBack or InfoCallback.

Format

int ScreenClearCallback(

int * UserData

);

Inputs

Outputs

None.

Returns

None.