| Previous | Contents | Index |
The following sections describe the individual callout routines. Each description includes the following:
The LGI$ICR_AUTHENTICATE callout routine authenticates passwords.
LGI$ICR_AUTHENTICATE arg_vector ,context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing callbacks and login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.
All logins involving a password invoke the LGI$ICR_AUTHENTICATE callout routine. The routine is not called for subprocesses, network jobs invoked by proxy logins, or logged-in DECterm sessions.The following pointers are used in password authentication:
- Longword LGI$A_ICR_PWDCOUNT points to a location that contains the number of OpenVMS passwords for a particular account. Nonexistent accounts are assigned a password count of 1 to avoid revealing them by the absence of a password prompt.
- For DECwindows logins only, longword LGI$A_ICR_PWD1 points to a location that contains the user's primary password.
- For DECwindows logins only, longword LGI$A_ICR_PWD2 points to a location that contains the user's secondary password, if applicable.
For all logins except DECwindows logins, the LGI$ICR_AUTHENTICATE callout routine may use the following callback routine sequence:
- Call LGI$ICB_PASSWORD for standard password prompting with an optional nonstandard prompt and the option of checking or just returning the password or other information obtained.
- Call LGI$ICB_GET_INPUT for completely customized prompting for each required piece of authentication information.
For DECwindows logins, neither the LGI$ICB_PASSWORD callback routine nor the LGI$ICB_GET_INPUT callback routine needs to be called. The user enters the password using the DECwindows login dialog box before LOGINOUT issues the LGI$ICR_AUTHENTICATE callout.
For a complete description of the DECwindows flow of control, see the description of the LGI$ICR_DECWINIT callout routine.
All logins involving a password may invoke the LGI$ICB_VALIDATE callback routine. This routine validates against SYSUAF.DAT passwords obtained by customized prompting using descriptors for the user name and passwords. Optionally, the login may call the LGI$_ICB_CHECK_PASS callback routine to validate passwords. For interactive jobs, the LGI$ICR_AUTHENTICATE routine should check the DISUSER flag using the LGI$ICB_DISUSER callback routine to preserve the consistency of the invalid user behavior for disabled accounts. For other types of jobs, use the LGI$ICR_CHKRESTRICT callout routine to check the DISUSER flag.
Note
LOGINOUT checks the DISUSER flag as part of the authentication process because, if it is checked later, an intruder could determine that the correct user name and password had been entered and that the account is disabled. This is deliberately hidden by keeping the user in the retry loop for a disabled account.If the DISUSER flag is checked with other access restrictions in the authorization portion, this causes an immediate exit from LOGINOUT.
Break-in detection, intrusion evasion, and security auditing are done in the case of any failure return from LGI$ICR_AUTHENTICATE.
If this routine returns LGI$_SKIPRELATED, the user is fully authenticated, and no further authentication is done by either the site or OpenVMS. If this routine returns an error for an interactive job, the system retries the identification and authentication portions of LOGINOUT. For character-cell terminals, this consists of calling the LGI$ICR_IDENTIFY and LGI$ICR_AUTHENTICATE callout routines; for DECwindows terminals, this consists of calling the LGI$ICR_DECWINIT routine. The number of retries is specified by the SYSGEN parameter LGI_RETRY_LIM.
SS$_NORMAL Access permitted; continue policy checks. LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_AUTHENTICATE callout routine in subsequent images and calls to the associated OpenVMS policy function. Other Disallow the login; perform break-in detection, intrusion evasion, and security auditing. For interactive logins, retry identification and authentication portions of LOGINOUT, up to the number specified in the SYSGEN parameter LGI_RETRY_LIM.
Perform standard password prompting and validation.
The LGI$ICR_CHKRESTRICT callout routine may be used to check site-specific access restrictions that are not usually included in the OpenVMS login.
LGI$ICR_CHKRESTRICT arg_vector ,context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing callbacks and login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.
All logins call this routine after the password is authenticated to allow the site to check other access restrictions. The site may check its own access restrictions and any of the following OpenVMS access restrictions:
Access Restriction Callback Routine Used to Check Restriction Account expiration LGI$ICB_ACCTEXPIRED Password expiration LGI$ICB_PWDEXPIRED Account disabled LGI$ICB_DISUSER Access modes and times LGI$ICB_MODALHOURS
SS$_NORMAL Access permitted; continue policy checks, including all of the normal OpenVMS policy functions associated with the callback routines used to check restrictions. LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_CHKRESTRICT callout routine in subsequent images and calls to the associated OpenVMS policy functions. Other Disallow the login.
Check password expiration, check DISUSER flag, check account expiration, and check restrictions on access time.
The LGI$ICR_DECWINIT callout routine enables site-specific initialization functions for logins from the DECwindows session manager.
LGI$ICR_DECWINIT arg_vector ,context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing site-specified callbacks and login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.
LOGINOUT invokes the LGI$ICR_DECWINIT callout routine at the start of a DECwindows session login. This callout routine does not support a return status of LGI$_SKIPRELATED. Returning LGI$_SKIPRELATED for this callout causes unpredictable results. Use the LGI$ICR_DECWINIT callout routine only to prepare other callout routines for a DECwindows login.After issuing the LGI$ICR_DECWINIT callout, LOGINOUT performs the following tasks:
- Creates the DECwindows login dialog box and reads the user name and password entered by the user
- Calls the LGI$ICR_IDENTIFY callout
- Obtains the user authorization file (UAF) record
If the UAF record specifies two passwords, the DECwindows login dialog box is amended to prompt for the second password, and the listed tasks are repeated.- Issues the LGI$ICR_AUTHENTICATE callout
- If the LGI$ICR_AUTHENTICATE callout routine did not return LGI$_SKIPRELATED, validates the passwords against the UAF record
The LGI$ICR_IDENTIFY and LGI$ICR_AUTHENTICATE callouts may create additional DECwindows dialog boxes to communicate with the user, but the initial dialog box must be created by LOGINOUT.
SS$_NORMAL Access permitted; continue policy checks. LGI$_SKIPRELATED Not supported. Returning this status will cause unpredictable behavior. Other Disallow the login.
Create dialog box, read user name and password, and call the identification and authentication routines.
The LGI$ICR_FINISH callout routine permits the site program to take final local action before exiting from LOGINOUT.
LGI$ICR_FINISH arg_vector ,context ,user_cond_value
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing callbacks and login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.user_cond_value
OpenVMS usage: cond_value type: longword_unsigned access: read only mechanism: by value
SS$_NORMAL for successful login; otherwise, reason for failure.
The site program calls this routine immediately before exiting to take any final local actions relative to the login process. There is no OpenVMS login security policy associated with LGI$ICR_FINISH.LGI$ICR_FINISH does not affect login completions because the login is audited before the routine is invoked. The routine has no effect on error recovery when a login fails, and it cannot cause a successful login to fail.
Typical site action may include the following:
- Override job quotas
- Stack CLI command procedures by examining and modifying the logicals PROC1 through PROC9
Caution
For DECwindows session manager logins, be careful modifying the command procedure stack to avoid adversely affecting the command file that invokes the session manager.- Other postlogin processing
LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_FINISH callout routine in subsequent images.
None.
The LGI$ICR_IACT_START callout routine may perform initialization functions for logins from interactive character-cell terminals.
LGI$ICR_IACT_START arg_vector ,context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing callbacks and login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.
This routine makes the first contact for all interactive logins from other than DECwindows terminals after opening the input and output files but before any other dialogue with the user.At this point, the site should be preparing to augment or replace the OpenVMS system password routine. The callback routine LGI$ICB_GET_SYSPWD provides access to the system password routine. However, because LGI$ICB_GET_SYSPWD returns only on success, the site design should consider what action to take in case LGI$ICB_GET_SYSPWD does not return control to LGI$ICR_IACT_START.
The LGI$ICR_IACT_START routine can use the LGI$ICB_GET_INPUT callback routine to:
- Get input from the user
- Use an OpenVMS RMS record access block (RAB) to establish appropriate terminal mode settings
SS$_NORMAL Access permitted; continue OpenVMS system password routine. LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_IACT_START callout routine in subsequent images and calls to the associated OpenVMS policy function. Other Exit quietly to preserve the illusion of an inactive line.
Get the system password.
The LGI$ICR_IDENTIFY callout routine identifies the user from the user name input.
LGI$ICR_IDENTIFY arg_vector ,context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Returns status indicating whether and how to proceed with the login.
arg_vector
OpenVMS usage: vector type: vector_longword_unsigned access: modify mechanism: by reference
Vector containing callbacks and useful login information.context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Pointer to site's local context.
The LGI$ICR_IDENTIFY callout routine is invoked for all types of login procedures. If the site uses the standard OpenVMS DECwindows dialogue, the identification routine may be called more than once for accounts with two passwords.If you plan to replace the standard OpenVMS identification processing, consider the following:
Calls to LGI$ICR_IDENTIFY are always followed by validation of the presence of the user name in the system authorization file, unless the routine is invoked for a subprocess.
- For logins from character-cell terminals, obtain the user name using one of the following:
- A dialogue with the user. The site can access OpenVMS user name processing to obtain the standard prompt or a specialized prompt by invoking the LGI$ICB_USERPROMPT callback routine. Alternatively, the site may invoke the LGI$ICB_GET_INPUT callback routine to communicate with the user.
- Site-specific equipment, for example, a card reader or some other authentication device.
- Autologins. The site may do the identification portion of the standard OpenVMS autologin by invoking the LGI$ICB_AUTOLOGIN callback routine.
- For logins from the DECwindows Session Manager, LOGINOUT invokes the callout module's LGI$ICR_IDENTIFY callout routine after obtaining the user name and putting it in LGI$A_ICR_USERNAME. The LGI$ICR_IDENTIFY callout routine can provide any additional checking of the user name that may be required.
- For batch jobs, network jobs, logged-in DECterm sessions, and subprocesses, the site may use the LGI$ICR_IDENTIFY routine to verify information without a user dialogue.
SS$_NORMAL Access permitted; continue policy checks. LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_IDENTIFY callout routine in subsequent images and calls to the associated OpenVMS policy function. Other Disallow the login.
Perform standard OpenVMS user name prompting and parsing.
| Previous | Next | Contents | Index |