VAM provides an API for allowing user-written applications to use LDAP, RADIUS 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.
The API allows VAM to be incorporated into user-written applications to control access to those applications. The API allows authentication via LDAP, RADIUS, or via the local system UAF.
This can be used by a business that uses normal operating-system access for its internal functions, but which may need further controlled access to specific applications that interface to counterparts on remote systems. In this case, VAM provides an additional layer of security for access to that application.
The authentication process begins with the user calling the VMSAuthenticate function, providing the username for the user, the type of authentication to perform and callbacks necessary to carry on a further dialog if needed.
For LDAP processing, the authentication routines carry on the dialog with the LDAP server, handling all the internal processing necessary. The user must configure VAM to specify the correct LDAP server and search criteria (e.g., the LDAP filter to use) to be used for the queries.
For LOCALUAF processing, the authentication routines perform many of the same checks that the VMS LOGINOUT processing does in order to validate the user.
The authentication routines will not carry on the actual dialog with the user. The user program, by supplying the dialog callbacks, will be required to do the actual dialog, using prompts supplied by the authentication routines. In this way, the user may tailor this to the user's specific environment (video terminal, DECwindows application, etc).
When prompting for data via the dialog callbacks, the user is responsible for disabling terminal echo prior to reading the information, and re-enabling it after reading the information, and may be responsible (depending on the type of authentication being performed) for performing edits on the input data (such as being of proper length and type).
The basic processing will be as follows:
· The user is prompted for the username within the context of the user program.
· The user program calls VMSAuthenticate() to initialize processing. The first parameter to this function determines the authentication mechanism to use (LDAP, RADIUS or LOCALUAF).
· VMSAuthenticate may use the callback routines to obtain more information from the user or to display information to the user.
· VMSAuthenticate will return to the original caller with a status indicating whether the user has been authenticated.
When compiling a source module that will call the VMSAuthenticate function, include the file VAM:VMSAUTHENTICATE.H.
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-enabled programs must be installed with CMKRNL privileges. If this is not done, they will be unable to successfully parse the VAM configuration file. For example:
$ INSTALL ADD MYPROGRAM.EXE /PRIV=CMKRNL
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.
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. 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.
int VMSAuthenticate
(
char *AuthenticationType,
char *Username,
char *Password,
int *(*IOCallback)(),
int *(*InfoCallback)(),
void *(*TimeoutCallback)(),
void *(*ScreenClearCallback)(),
int *UserData,
char *Identifier,
struct vam_attr **UserAttributes,
0
);
· AuthenticationType - String (null-terminated) containing the type of authentication desired. Currently, must be LDAP, RADIUS, or LOCALUAF.
· Username - String (null-terminated) containing the username to be checked. The username is case-sensitive.
· Password - String (null-terminated) containing the password to be checked. Ignored when AuthenticationType is LDAP or RADIUS. 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.
· UserAttributes - The address of a struct vam_attr pointer. When attributes for a user are fetched, a pointer to a linked list of vam_attr structures will be returned in this variable.
· The final parameter (denoted by “0” above) is reserved for future use but must be specified.
The vam_attr structure is defined in the VMSAUTHENTICATE.H file, and has the following form:
struct vam_attr
{
char *attribute_name;
char *value;
struct vam_attr *next;
};
The fields within this structure are:
attribute_name - pointer to a character string that will contain the name of the attribute that was specified in the ATTRIBUTE keyword in the VAM:VAM_CONFIG.DAT file.
value - pointer to a character string that contains the value fetched for attribute_name. This will be NULL if no value was fetched.
next - pointer to the next attribute structure. This will be zero if the end of the attribute chain has been reached.
None.
SS$_NORMAL
Authentication successful.
SS$_ABORT
Authentication was aborted by the server
SS$_BADPARAM
• No username was supplied
• Authentication type was not LDAP, RADIUS, 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.
|
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.
int IOCallback
(
char * Prompt,
char * Response,
int MinRespLen,
int MaxRespLen,
int RespType,
int EchoFlag,
int Timeout,
int * UserData
);
· 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.
· 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).
· Response - character string (null-terminated) that contains the response returned by the user.
1 = successfully completed
0 = call was aborted. This will cause the authentication session to be terminated, with VMSAuthenticate returning a status of SS$_CANCEL.
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).
int InfoCallback(char *Prompt, int Timeout, int *UserData);
· Prompt - Character string (null-terminated) that contains the prompt to display.
· Timeout - Time (in seconds) to display the 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).
None.
1 = successfully completed
0 = call was aborted. This will cause the authentication session to be terminated, with VMSAuthenticate() returning a status of SS$_CANCEL.
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.
|
Note: The user program must not disable AST's via the VMS $SETAST system service. If this is done, timeouts won't be enforced.
|
void TimeoutCallback(int *UserData);
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).
None.
None.
This user application-supplied callback routine is used when the screen should be cleared subsequent to a call to IOCallBack or InfoCallback.
int ScreenClearCallback(int *UserData);
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).
None.
None.