VMS Authentication Module Administration & User's Guide
Chapter 3
Using VAM
Introduction
The VMS Authentication Module (VAM) provides users of OpenVMS systems controlled access to both user-written applications and the OpenVMS system overall using SecurID. It can be incorporated into an OpenVMS-based platform in two ways:
• Via an API that the user incorporates into a specific application to control access to that application
• On a system-wide basis via use of the LGI callouts for OpenVMS LOGINOUT.EXE.
This chapter describes the two mechanisms and how they are implemented.
The VAM API
The API allows VAM to be incorporated into user-written applications to control access to those applications. The API allows authentication via SecurID tokens 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 specific API calls are documented in chapter 4.
The API Authentication Philosophy
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 SECURID processing, the authentication routines carry on the dialog with the RSA Authentication Manager, handling all the internal processing necessary. This includes the capability to handle replicated servers, etc..
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 (SECURID 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.
Controlling LOCALUAF Access to the Application
Some installations may have several applications protected via VAM and using LOCALAUF processing, but which they want to further restrict access to. For example, the company may want the PAYROLL application restricted to only people from the payroll department, while the INVENTORY application might be restricted to salespeople.
VAM provides a mechanism for restricting access in VAM-enabled applications by using VMS rights ids. When adding the VAM interface to an application, the application programmers may add the identifier field to the VMSAuthenticate() function call (see chapter 4, Using the VAM API, for information on calling VMSAuthenticate). VAM then attempts to match identifier with a rights id in the UAF record for the username specified in the call to VMSAuthenticate. If a match is made, access is allowed; otherwise, access is denied.
If identifier is not specified or is blank when calling VMSAuthenticate, then identifier will default to VAM_UAF_ID. Therefore, the VAM_UAF_ID rights id must be granted to all VAM users using LOCALUAF processing if identifier is not specified in the call to VMSAuthenticate.
Note! There is no equivalent functionality for use when performing SECURID processing. Access in that case is solely determined by the RSA Authentication Manager.
For example, ABC corporation has three VAM-enabled applications using LOCALUAF processing: payroll, inventory and personnel. User John Doe will be allowed to access only INVENTORY, while Jane Doe will be allowed to access PERSONNEL and PAYROLL. To set these accounts up, the following steps may be used:
$ run sys$system:authorize
UAF> add/identifier payroll
%UAF-I-RDBADDMSG, identifier PAYROLL value %X80010003 added to rights database
UAF> add/identifier inventory
%UAF-I-RDBADDMSG, identifier INVENTORY value %X80010004 added to rights database
UAF> add/identifier personnel
%UAF-I-RDBADDMSG, identifier PERSONNEL value %X80010005 added to rights database
UAF> grant/identifier inventory johndoe
%UAF-I-GRANTMSG, identifier INVENTORY granted to JOHNDOE
UAF> grant/identifier payroll janedoe
%UAF-I-GRANTMSG, identifier PAYROLL granted to JANEDOE
UAF> grant/identifier personnel janedoe
%UAF-I-GRANTMSG, identifier PERSONNEL granted to JANEDOE
UAF> Exit
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-NAFNOMODS, no modifications made to network proxy database
%UAF-I-RDBDONEMSG, rights database modified
$
Then, when adding VAM to, for example, the payroll application, the call to VMSAuthenticate would be:
status = VMSAuthenticate("LOCALUAF", username, 0, &IOCallback,
&InfoCallback, &TimeoutCallback,
&ScreenClearCallback, 0, "payroll", 0, 0);
The VAM LGI Callouts
VAM may be incorporated into the OpenVMS login mechanism to control access to the entire system. VAM provides an OpenVMS shareable image, which the system manager can incorporate, using supported OpenVMS mechanisms, into the OpenVMS LOGINOUT mechanism. This image uses the SecurID protocols to supplement the standard OpenVMS login processing and provides the necessary user authentication to access the system as part of the login process.
Note! This section assumes the user has basic knowledge of how SecurID authentication works.
Sample VAM Login
The following example shows a login to a system for a user that has not yet established a PIN
$ SET HOST VOODOO
Welcome to OpenVMS (TM) IA64 Operating System, Version V8.2-1
Username: johndoe
Enter PASSCODE:
You must select a new PIN.
Do you want the system to generate
your new PIN? (y/n) [n] n
Enter a new PIN between 4 and 8 alphanumeric
characters:
Re-enter new PIN to confirm:
PIN accepted. Wait for the tokencode to
change, then enter a new PASSCODE:
PASSCODE accepted.
Welcome to OpenVMS IA64 V8.2-1
Last interactive login on Monday, 23-JAN-2006 12:04:50.21
Last non-interactive login on Friday, 2-DEC-2005 07:33:34.74
You have 1 new Mail message.
VOODOO_$
Controlling Access to the Callout
The system manager configures the system to use the LGI callouts. This may be done in two ways:
· Define the logical name VAM_REQUIRE_SECURID system-wide. If defined, all users are required to use SecurID authentication.
· Add the rights identifier VAM_LGI_SECURID to the system rights database. This identifier may then be granted to those users that will be required to use SecurID authentication.
In addition, there are two logical names that, if defined, determine what types of terminal devices DECterm (FTAnn:) and/or DECnet CTERM (RTAnn:) devices are required log in using SecurID: The logicals may be defined to any value; the software simply uses the existence of the logicals to operate.
VAM_ALLOW_DECTERM_LOGIN
Note! The system console (OPA0:) is never required to use SecurID processing, in order to prevent being locked-out of the system in the event of a network failure that prevents the VMS system from talking with the SecurID RSA Authentication Manager system(s).
Note! SSH logins are not affected by the VAM LGI callouts.
Other VAM-Specific Logical Names
General Logicals
These logical names are defined on all VAM systems. They are defined when the VAM_STARTUP command procedure is executed.
VAM
This logical points to the <install_device>:[VAM] directory.
VAM_ROOT
This logical points to <install_device>:[VAM.]. It may be used, for example, to specify the log file directory: VAM_ROOT:[LOG].
Logging Control Logicals
The following logical names are used to affect logging for the VAM software. The logicals are located in the VAM_SPECIFIC_STARTUP command procedure and are normally commented out. This logging is used to debug VAM installations, and should generally be used only when recommended by Process Software.
VAM_LOGFILE
This logical determines the location and name of the file used to log VAM transactions and errors.
VAM_CURRENT_TRACE_LEVEL
This logical determines the level of detail in the VAM log. The level is a combination of the following bit masks:
TRACE_EXECUTION (1) - traces general steps the VAM module is performing.
TRACE_EXECUTION_DEEP (2) - verbose tracking of the VAM module processing.
TRACE_INFO (4) - Tracks informational messages generated by the VAM module
TRACE_ERROR (8) - Logs errors encountered by the VAM module
This logical name is used to determine the level of detail in the SecurID logfile. This is a number from 1 to 65535, where 1 is the lowest level of tracing. This logical should never normally be defined, as it can have a severe impact on performance.
RSATRACEDEST
This logical defines the location and name of the SecurID log file. If this isn’t defined, output will go to the user’s terminal.
SecurID Files Used by VAM
The following files, used by SecurID processing, are found in the VAM directory. They should not normally be manipulated by the system manager:
SDSTATUS.12
This file is used by SecurID to keep track of the status of the RSA Authentication Manager servers and replicas. Each time a successful connection is made to a SecurID server, this file is rewritten.
SECURID.
This is the SecurID "node secret" file. It’s created after the first successful SecurID session.
