HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The following sections describe the individual callout routines. Each description includes the following:

• The format of the call command
• The anticipated information returned by the called routine
• The arguments presented to the called routine
• A general description of the routine
• Typical condition values that indicate the return status
• Associated OpenVMS policy function, that is, the standard LOGINOUT policy functions developed for OpenVMS compared with the site-provided policy functions

The LGI$ICR_AUTHENTICATE callout routine authenticates passwords.

Format

LGI$ICR_AUTHENTICATE arg_vector ,context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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.

Typical Condition Values

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.

Associated OpenVMS Policy Function

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.

Format

LGI$ICR_CHKRESTRICT arg_vector ,context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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

Typical Condition Values

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.

Associated OpenVMS Policy Functions

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.

Format

LGI$ICR_DECWINIT arg_vector ,context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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.

Typical Condition Values

SS$_NORMAL	Access permitted; continue policy checks.
LGI$_SKIPRELATED	Not supported. Returning this status will cause unpredictable behavior.
Other	Disallow the login.

Associated OpenVMS Policy Function

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.

Format

LGI$ICR_FINISH arg_vector ,context ,user_cond_value

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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

Typical Condition Values

LGI$_SKIPRELATED

Access permitted; omit calls to the LGI$ICR_FINISH callout routine in subsequent images.

Associated OpenVMS Policy Function

None.

The LGI$ICR_IACT_START callout routine may perform initialization functions for logins from interactive character-cell terminals.

Format

LGI$ICR_IACT_START arg_vector ,context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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

Typical Condition Values

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.

Associated OpenVMS Policy Function

Get the system password.

The LGI$ICR_IDENTIFY callout routine identifies the user from the user name input.

Format

LGI$ICR_IDENTIFY arg_vector ,context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Returns status indicating whether and how to proceed with the login.

Arguments

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.

Description

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:

• 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.

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.

Typical Condition Values

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.

Associated OpenVMS Policy Function

Perform standard OpenVMS user name prompting and parsing.