[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Utility Routines Manual


Previous Contents Index


LBR$SET_LOCATE

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.

LBR$SET_MODULE

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.

LBR$SET_MOVE

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.


Chapter 12
LOGINOUT (LGI) Routines

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:

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:

Each callout routine may access LOGINOUT's internal state and callback routines using a vector of entry points. The callback routines allow the callout routines to communicate with the user and to incorporate elements of the standard OpenVMS policy functions in a modular fashion.

12.1.2 Using LOGINOUT with External Authentication

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.

Note

The use of LOGINOUT callouts disables external authentication, making only the standard OpenVMS authentication policy available.

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


12.2 LOGINOUT Callouts

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

The callback routines enable the site's callout routines to communicate interactively with the user or to invoke other services provided by LOGINOUT. Table 12-2 briefly describes the LOGINOUT callback routines. See Section 12.5 for detailed descriptions of these 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:

Section 12.3.5 contains a sample LOGINOUT program.

12.3.1 Calling Environment

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:

The callout routine's return status must be one of the following:
Return Status Interpretation
SS$_NORMAL Access permitted; continue policy checks. Execute next policy image or OpenVMS policy function associated with this callout, if applicable.
LGI$_SKIPRELATED Access permitted; discontinue checks. Continue with the login without further processing of login policy functions associated with this callout, including relevant OpenVMS policy functions built into LOGINOUT.
Other Disallow the login:
  • Perform break-in detection and intrusion evasion, if appropriate.
  • Perform security audit.
  • Allow additional login attempts up to system-specified repeat limit, if appropriate.

Note

When a fatal error occurs, the policy module may terminate the login by signaling a severe error using the BLISS built-in SIGNAL_STOP or by calling LIB$SIGNAL. (See the OpenVMS RTL Library (LIB$) Manual for a description of the LIB$SIGNAL routine.) LOGINOUT will do a security audit, but it will not perform break-in detection or intrusion evasion.

Avoid using a severe error termination unless the LOGINOUT process state is in jeopardy. LOGINOUT should terminate with a clean exit and a disallowed login whenever possible.

12.3.2 Callout Organization

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:

Note

LOGINOUT is installed with privileges. Therefore, any image containing LOGINOUT callout routines must be installed.
If the identifying logical is a list of several images, the images are sequentially activated in the listed order. If a specified image is not activated, the login fails.

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.

Note

Callouts are not invoked when LOGINOUT initiates the STARTUP process during system bootstrap.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4493PRO_026.HTML