Document revision date: 19 July 1999

The LBR$SET_LOCATE routine sets the record access of LBR subroutines to locate mode.

Format

LBR$SET_LOCATE library_index

RETURNS

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

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

Description

Librarian record access may be set to move mode (the default set by LBR$SET_MOVE) or locate mode. The setting affects the operation of the LBR$GET_RECORD routine.

If move mode is set (the default), LBR$GET_RECORD copies the requested record to the specified user buffer. If locate mode is set, the record is not copied. Instead, the outbufdes descriptor is set to reference the internal LBR subroutine buffer that contains the record.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$SET_MODULE routine reads, and optionally updates, the module header associated with a given record's file address (RFA).

Format

LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc]

RETURNS

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

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

rfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Record's file address (RFA) associated with the module header. The rfa argument is the address of a 2-longword array containing the RFA returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.

bufdesc

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Buffer that receives the module header. The bufdesc argument is the address of a string descriptor pointing to the buffer that receives the module header. The buffer must be the size specified by the symbol MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option. The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and $CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB.

buflen

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

Length of the module header. The buflen argument is the address of a longword receiving the length of the returned module header.

updatedesc

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Additional information to be stored with the module header. The updatedesc argument is the address of a string descriptor pointing to additional data that the Librarian stores with the module header. If you include this argument, the Librarian updates the module header with the additional information.

Description

If you specify bufdesc, the LBR routine returns the module header into the buffer. If you specify buflen, the routine also returns the buffer's length. If you specify updatedesc, the routine updates the header information.

You define the maximum length of the update information (by specifying a value for CRE$L_UHDMAX) when you create the library. The Librarian zero-fills the information if it is less than the maximum length or truncates it if it exceeds the maximum length.

Condition Values Returned

LBR$_HDRTRUNC	Buffer supplied to hold the module header was too small.
LBR$_ILLCTL	Specified library control index not valid.
LBR$_ILLOP	Error. The updatedesc argument was supplied and the library was a Version 1.0 library or the library was opened only for read access.
LBR$_INVRFA	Specified RFA does not point to a valid module header.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$SET_MOVE routine sets the record access of LBR subroutines to move mode.

Format

LBR$SET_MOVE library_index

RETURNS

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

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

Description

Librarian record access may be set to move mode (the default, set by LBR$SET_MOVE) or locate mode. The setting affects the operation of the LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD copies the requested record to the specified user buffer. For details, see the description of LBR$GET_RECORD.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

The information in this chapter is intended for programmers implementing the requirements of site security administrators or third-party security software producers.

This chapter differs from other parts of this book because it does not deal strictly with callable routines that are internal to the OpenVMS system. The LOGINOUT callout routines are designed by site security administrators. The callback routines are invoked by the callout routines.

12.1 Introduction to LOGINOUT

The OpenVMS login security program (LOGINOUT.EXE) supports calls to site-specific routines (LOGINOUT callout routines). These callout routines support custom login security programs such as smart card programs, pocket authenticator programs, and other alternative identification and authentication programs. The callout routines permit sites to combine portions of the LOGINOUT security policy functions with site login security functions to establish a customized login security environment.

12.1.1 The LOGINOUT Process

The site security administrator provides LOGINOUT with the following:

• One or more shareable images comprised of modules that include callout routines
• A list of the shareable images

As login events occur, LOGINOUT invokes the applicable callout, thus enabling the site to replace or augment each event using site-specific modifications.

The site may provide multiple callout images. The images are invoked in the order in which they are declared to the system. Each image contains an independently developed set of policy routines.

Each callout routine may do one of the following:

• Enforce site-specific policy functions
• Defer to subsequent routines
• Use elements of the standard OpenVMS policy functions

The following sections describe LOGINOUT's interaction with the external authentication policy supported by OpenVMS. For more information about single sign-on and user authentication, see the OpenVMS Guide to System Security.

Overview of External Authentication

At sites using external authentication, all authentication decisions for users are actually made by the LAN manager rather than OpenVMS; however, OpenVMS account restrictions and quota checks remain in effect.

To access the system, users must provide their LAN manager user ID and password at the login prompt. If local password synchronization is required, one of the following messages is displayed indicating the outcome of the synchronization attempt:

OpenVMS password has been synchronized with network password Not able to synchronize OpenVMS password with network password

These messages can be suppressed on a per-user basis by setting the DISREPORT flag.

Specifying Local Authentication

The login command line supports the /LOCAL_PASSWORD qualifier. This qualifier indicates to LOGINOUT that the user intends to override external authentication by using their OpenVMS user name and password. This is considered a temporary means for logging in to the system when the external authentication service is unavailable. To use this qualifier, you must have SYSPRV privilege.

When a user has logged in locally, the following message is displayed:

Local logon successful; network logon service not used

Locally authenticated users are not subject to OpenVMS password policy, since the system manager specified that these users are subject to external authentication policy only.

12.1.3 The LOGINOUT Data Flow

Figure 12-1 provides an overview of the data flow between LOGINOUT, the callout routines, and site-specific shareable images that can include one or more callout modules.

Figure 12-1 LOGINOUT Callout Routines Data Flow

This section introduces the callouts that LOGINOUT uses to interface with the site-specific callout modules in the shareable images. The section also describes a set of callback routines that the callout routines can use to invoke services provided within LOGINOUT.

12.2.1 LOGINOUT Callout Routines

LOGINOUT calls a different site-provided callout routine at each important step in its execution. Table 12-1 briefly describes the LOGINOUT callouts. See Section 12.4 for detailed descriptions of these routines.

Table 12-1 LOGINOUT Callouts

Callout	Description
LGI$ICR_AUTHENTICATE	Authenticates the user account at login
LGI$ICR_CHKRESTRICT	Checks additional security restrictions
LGI$ICR_DECWINIT	Prepares for interactive contact with DECwindows users
LGI$ICR_FINISH	Gives site-specific code final control of the login process
LGI$ICR_IACT_START	Prepares for interactive contact with users who are not using the DECwindows interface
LGI$ICR_IDENTIFY	Identifies the user at login
LGI$ICR_INIT	Initializes context variable
LGI$ICR_JOBSTEP	Indicates the start of each step in a batch job
LGI$ICR_LOGOUT	Prepares for logout

12.2.2 LOGINOUT Callback Routines

Table 12-2 LOGINOUT Callback Routines

Routine	Description
LGI$ICB_ACCTEXPIRED	Checks for account expiration
LGI$ICB_AUTOLOGIN	Verifies that standard rules for autologin apply
LGI$ICB_CHECK_PASS	Checks the entered password against the user authorization file (UAF) record
LGI$ICB_DISUSER	Checks for DISUSER flag
LGI$ICB_GET_INPUT	Enables interaction with the user
LGI$ICB_GET_SYSPWD	Checks system password for character-cell interactive logins
LGI$ICB_MODALHOURS	Checks for restrictions on access modes and access hours
LGI$ICB_PASSWORD	Generates prompts, reads input, and optionally validates input against system user authorization file (SYSUAF.DAT)
LGI$ICB_PWDEXPIRED	Checks for password expiration
LGI$ICB_USERPROMPT	Prompts for and reads input for character-cell interactive logins
LGI$ICB_USERPARSE	Parses input buffer data for character-cell interactive logins
LGI$ICB_VALIDATE	Validates the user name and password against the system user authorization file (SYSUAF.DAT)

12.3 Using Callout Routines

This section describes:

• The calling environment
• The callout routines and how they are organized and activated
• The callout routines interface

The general form for invoking the callout routines is as follows:

return-status = routine (standard_arguments_vector, context, routine_specific_args)

The call elements include the following:

• Standard argument vector: contains pointers to LOGINOUT data structures and callback routines for communicating with the user
• Context: a longword that the site-specific program may use to store a pointer to local context
• Routine-specific arguments: arguments directly related to the specific routine

A site may use several callout modules. For example, assume that the site is working with another program that uses logins or the site involves logins for various devices or logins at various security levels.

LOGINOUT invokes the callout routines using a vector of entry points rather than the routine name. Each vector entry point corresponds to a policy function, and the first vector entry contains a count of the entry points in the vector, thus making the vector extendable. Figure 12-2 shows how a callout routine vector is organized.

Figure 12-2 Callout Organization

Note that entry points may be accessed randomly. When a site-provided callout module does not provide a routine for a particular callout, the site must enter a 0 value as a placeholder into the corresponding vector location.

Callout modules may modify the vector during execution so that following events invoke different routines. For example, one of the initialization callout routines could modify the vector in anticipation of a following call to a different terminal or different job type, or it might zero the number of entry points to disable further calls to callout routines contained in the current callout module.

12.3.3 Activating the Callout Routines

A site activates the LOGINOUT callouts by identifying its callout images using the system executive-mode logical name LGI$LOGINOUT_CALLOUTS. The logical name may contain one value or a list of values that identify the callout images using either the:

• File name of a module located in SYS$SHARE:*.EXE
• Name of an executive-mode system logical name representing a full file specification

To protect against intrusion, the site uses the system parameter LGI_CALLOUTS to specify the number of callout images. If this value is nonzero and the supplied number of callout images does not correspond to the value, the login fails.

Sites that want to control their job creation process and authenticate each network login by implementing LOGINOUT callouts must set the NET_CALLOUTS system parameter to 255. This ensures that LOGINOUT is called for every network login --- bypassing any existing server processes.

The default value of NET_CALLOUTS (0) could bypass the LOGINOUT callouts and allow NET$ACP to perform its own proxy and login authentication. See the file SYS$SYSTEM:NETSERVER.COM for an example of how NET$ACP performs its own authentication and management of server processes.

Parameter values 1 to 254 are reserved by Compaq for future use.

	privacy and legal statement
4493PRO_026.HTML