The LOGINOUT (LGI) routines are used by programmers implementing
the requirements of site security administrators or third-party
security software producers.
The LGI routines do not deal strictly with callable routines that
are internal to the OpenVMS system. The LOGINOUT callout routines
(whose names begin with LGI$ICR_) are designed by site security
administrators. The callback routines (whose names begin with
LGI$ICB_) are invoked by the callout routines.
1 – LGI$ICR_AUTHENTICATE
The LGI$ICR_AUTHENTICATE callout routine authenticates passwords.
Format
LGI$ICR_AUTHENTICATE arg_vector ,context
1.1 – 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.
1.2 – 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.
1.3 – 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:
o 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.
o For DECwindows logins only, longword LGI$A_ICR_PWD1 points to
a location that contains the user's primary password.
o 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:
o 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.
o 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.
1.4 – 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.
1.5 – Associated OpenVMS Policy Function
Perform standard password prompting and validation.
2 – LGI$ICR_CHKRESTRICT
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
2.1 – 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.
2.2 – 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.
2.3 – 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 LGI$ICB_ACCTEXPIRED
expiration
Password LGI$ICB_PWDEXPIRED
expiration
Account disabled LGI$ICB_DISUSER
Access modes and LGI$ICB_MODALHOURS
times
2.4 – 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.
2.5 – Associated OpenVMS Policy Functions
Check password expiration, check DISUSER flag, check account
expiration, and check restrictions on access time.
3 – LGI$ICR_DECWINIT
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
3.1 – 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.
3.2 – 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.
3.3 – 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:
o Creates the DECwindows login dialog box and reads the user
name and password entered by the user
o Calls the LGI$ICR_IDENTIFY callout
o 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.
o Issues the LGI$ICR_AUTHENTICATE callout
o 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.
3.4 – 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.
3.5 – Associated OpenVMS Policy Function
Create dialog box, read user name and password, and call the
identification and authentication routines.
4 – LGI$ICR_FINISH
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
4.1 – 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.
4.2 – 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.
4.3 – 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:
o Override job quotas
o 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.
o Other postlogin processing
4.4 – Typical Condition Values
LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_
FINISH callout routine in subsequent images.
4.5 – Associated OpenVMS Policy Function
None.
5 – LGI$ICR_IACT_START
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
5.1 – 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.
5.2 – 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.
5.3 – 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:
o Get input from the user
o Use an OpenVMS RMS record access block (RAB) to establish
appropriate terminal mode settings
5.4 – 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.
5.5 – Associated OpenVMS Policy Function
Get the system
password.
6 – LGI$ICR_IDENTIFY
The LGI$ICR_IDENTIFY callout routine identifies the user from the
user name input.
Format
LGI$ICR_IDENTIFY arg_vector ,context
6.1 – 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.
6.2 – 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.
6.3 – 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:
o 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.
o 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.
o 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.
6.4 – 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.
6.5 – Associated OpenVMS Policy Function
Perform standard OpenVMS user name prompting and parsing.
7 – LGI$ICR_INIT
The LGI$ICR_INIT callout routine may perform any required
initialization functions.
Format
LGI$ICR_INIT arg_vector ,context
7.1 – 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.
7.2 – 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.
7.3 – Description
This routine is called for all job types before opening input
and output files. If desired, the callout routine may initialize
the context argument, which LOGINOUT subsequently passes to each
callout routine with the address of local storage specific to the
callout image.
7.4 – Typical Condition Values
SS$_NORMAL Access permitted; continue policy checks.
LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_
INIT callout routine in subsequent images.
Other Disallow the login.
7.5 – Associated OpenVMS Policy Function
None.
8 – LGI$ICR_JOBSTEP
The LGI$ICR_JOBSTEP callout routine signals the start of each
batch job step.
Format
LGI$ICR_JOBSTEP input_file_name ,context ,write_fao
8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Not applicable.
8.2 – Arguments
input_file_name
OpenVMS usage:descriptor
type: character string
access: read
mechanism: by reference
The name of the input file.
context
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Pointer to site's local context.
write_fao (fao_string[,arg1[,arg2][,...]]])
OpenVMS usage:routine
type: procedure
access: read
mechanism: by reference
Address of a routine that may be called to format and display
output. The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the VSI OpenVMS System Services Reference Manual for
more information.)
8.3 – Description
The LGI$ICR_JOBSTEP routine alerts the site of each job step in a
batch job. The routine is invoked as LOGINOUT processes each job
step. For the first job step, the LGI$ICR_JOBSTEP callout routine
is invoked immediately following the LGI$ICR_IDENTIFY callout
routine. For all other job steps, it is the only callout routine
that is invoked.
The routine is provided with the input file name, but the input
file is not open when the routine is called. For the first job
step, the LGI$ICR_INIT callout routine may provide the batch
job step routine with context. For other job steps, the context
argument is a null.
For all job steps except the first, the output file is open, and
the routine specified by the write_fao argument is available.
There is no OpenVMS policy associated with LGI$ICR_JOBSTEP.
8.4 – Typical Condition Values
LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_
or any error JOBSTEP callout routine in subsequent images.
value
8.5 – Associated OpenVMS Policy Function
None.
9 – LGI$ICR_LOGOUT
The LGI$ICR_LOGOUT callout routine permits the site callout
images to respond to the DCL command LOGOUT.
NOTE
This routine is not called if the calling process is deleted
with STOP/PROCESS ($DELPRC). If the calling terminal is
disconnected when logout occurs, this routine must not
produce output.
Format
LGI$ICR_LOGOUT username ,processname ,creprc_flags ,write_fao
9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Returns logout status from the site program.
9.2 – Arguments
username
OpenVMS usage:descriptor
type: character string
access: read
mechanism: by reference
User name.
processname
OpenVMS usage:descriptor
type: character string
access: read
mechanism: by reference
Process name.
creprc_flags
OpenVMS usage:mask_longword
type: longword_unsigned
access: read
mechanism: by reference
Process creation status flags.
write_fao (fao_string[,arg1[,arg2][,...]]])
OpenVMS usage:routine
type: procedure
access: read
mechanism: by reference
Procedure for writing data. The value is 0 if output is not
permitted.
Address of a routine that may be called to format and display
output. The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the VSI OpenVMS System Services Reference Manual for
more information.)
9.3 – Description
The LGI$ICR_LOGOUT routine is invoked after auditing is completed
and immediately before LOGOUT prints the logout message. This
routine cannot prevent the logout from finishing, but it may
prevent display of the standard logout message.
9.4 – Typical Condition Values
LGI$_SKIPRELATED Access permitted; omit calls to the LGI$ICR_
or any error LOGOUT callout routine in subsequent images.
value
9.5 – Associated OpenVMS Policy Function
None.
10 – LGI$ICB_ACCTEXPIRED
The LGI$ICB_ACCTEXPIRED callback routine checks for account
expiration.
Format
LGI$ICB_ACCTEXPIRED
10.1 – Returns
No value. Does not return on failure.
10.2 – Arguments
None.
10.3 – Description
The site can use this callback routine to determine if the
specified account is expired. If the account is expired, the
LGI$ICB_ACCTEXPIRED callback routine:
o Writes its standard error message to the user terminal, if a
terminal exists
o Does not return control to the caller
10.4 – Condition Values Returned
None.
11 – LGI$ICB_AUTOLOGIN
The site may use the LGI$ICB_AUTOLOGIN callback routine to
determine whether the standard OpenVMS autologin functionality
applies for this terminal.
Format
LGI$ICB_AUTOLOGIN
11.1 – Returns
OpenVMS usage:value
type: longword (unsigned)
access: write only
mechanism: by value
True (logical 1) if autologin enabled; 0 otherwise.
11.2 – Arguments
None.
11.3 – Description
If the standard OpenVMS autologin functionality applies, the
callback routine returns the user name to the site program using
the standard argument vector so that the autologin process may
continue.
The autologin determination is made before the site prompts for
the user passwords. The callback routine is applicable only for
interactive character-cell logins.
NOTE
Standard OpenVMS policy uses autologin only on directly
connected or LAT connected character-cell terminals. The
LGI$ICB_AUTOLOGIN callback routine checks the automatic
login file (ALF) SYS$SYSTEM:SYSALF.DAT to make the
determination.
A DECwindows callout can include a method for doing a
DECwindows autologin. In that case, the callout routine
should set the autologin flag to true before returning
control to LOGINOUT.
11.4 – Condition Values Returned
None.
12 – LGI$ICB_CHECK_PASS
The LGI$ICB_CHECK_PASS callback routine checks a password against
the user authorization file (UAF) record.
Format
LGI$ICB_CHECK_PASS password ,uaf_record ,pwd_number
12.1 – Returns
OpenVMS usage:value
type: longword (unsigned)
access: write only
mechanism: by value
The value 1 for a valid password. The value -4 for an invalid
password.
12.2 – Arguments
password
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
User-supplied password to be validated.
uaf_record
OpenVMS usage:buffer
type: vector_byte (unsigned)
access: read only
mechanism: by reference
Address of buffer containing UAF record.
pwd_number
OpenVMS usage:value
type: longword (unsigned)
access: read only
mechanism: by value
Password number, 0 (primary) or 1 (secondary).
12.3 – Description
The site uses this callback routine to check the user-supplied
password against the UAF record provided as the second argument.
If the password is valid, the routine returns a 1 in R0; if the
password is invalid, the routine returns a -4 in R0.
12.4 – Condition Values Returned
None.
13 – LGI$ICB_DISUSER
The LGI$ICB_DISUSER callback routine checks the disabled user
account flag.
Format
LGI$ICB_DISUSER action
13.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
13.2 – Argument
action
OpenVMS usage:value
type: longword (unsigned)
access: read only
mechanism: by value
This argument can take two values:
If Value of
Action Is... Then...
LGI$_DISUSER_STOP Do not return on error.
LGI$_DISUSER_ Return LGI$_DISUSER or SS$_NORMAL.
RETURN
13.3 – Description
The site can use this callback routine to establish the standard
OpenVMS action if the DISUSER flag is set.
13.4 – Condition Values Returned
LGI$_DISUSER
SS$_NORMAL
14 – LGI$ICB_GET_INPUT
The LGI$ICB_GET_INPUT callback routine enables interaction with
the user.
Format
LGI$ICB_GET_INPUT rab ,flags
14.1 – Returns
No value. Does not return on failure.
14.2 – Arguments
rab
OpenVMS usage:rab
type: longword (unsigned)
access: modify
mechanism: by reference
Data structure used to set up a read-with-prompt OpenVMS RMS
operation. Normally you pass the RAB address in LGI$A_ICR_INPUT_
RAB.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A data structure that determines the error response as follows:
Flags
ValueResponse
0 Normal error message.
1 LOGINOUT exits quietly.
2 Normal error message; however, the callback routine returns
control to the caller rather than exiting on timeout
(timeout status is in RAB).
14.3 – Description
The LGI$ICB_GET_INPUT callback routine invokes the LOGINOUT input
routine to enable interaction with character-cell terminal users.
The read operation provides a timeout to ensure that the UAF
record does not remain locked if the user presses Ctrl/S.
14.4 – Condition Values Returned
No return value. Examine status in RAB to determine the results
of the read operation.
15 – LGI$ICB_GET_SYSPWD
The LGI$ICB_GET_SYSPWD callback routine validates the system
password.
Format
LGI$ICB_GET_SYSPWD
15.1 – Returns
No value. Does not return on failure.
15.2 – Arguments
None.
15.3 – Description
This callback routine performs standard system password-checking
for interactive logins on character-cell terminals only.
If the system password is validated, this callback routine
returns control to the caller. If the system password is not
validated, the LOGINOUT image exits, and the login is terminated.
15.4 – Condition Values Returned
None.
16 – LGI$ICB_MODALHOURS
The LGI$ICB_MODALHOURS callback routine checks for restrictions
on access modes and access hours.
Format
LGI$ICB_MODALHOURS
16.1 – Returns
No value. Does not return on failure.
16.2 – Arguments
None.
16.3 – Description
The site uses this callback routine to establish the access
modes and access hours available to the user. If the user is
not authorized to access the system from this login class (batch,
dialup, local, remote, network) at this time (as specified in the
UAF), the callback routine:
o Writes its standard error message to the user terminal, if
there is a terminal
o Does not return control to the caller
16.4 – Condition Values Returned
None.
17 – LGI$ICB_PASSWORD
The LGI$ICB_PASSWORD callback routine produces the specified
password prompt and then processes the input.
Format
LGI$ICB_PASSWORD password_number ,prompt ,buffer
17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
17.2 – Arguments
password_number
OpenVMS usage:value
type: longword (unsigned)
access: read only
mechanism: by value
A numeric value indicating which password to prompt for and what
action to take on it:
ValuePrompt for
0 Primary password and validate it
1 Secondary password and validate it
-1 Primary password but do not validate it
-2 Secondary password but do not validate it
-3 Arbitrary 32-character value returned to buffer specified in
buffer
If the value is -3, you must specify the prompt argument and the
buffer argument.
prompt
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
String that must begin with "cr,lf". If this argument is not
supplied, the standard prompt is used.
buffer
OpenVMS usage:character string
type: string descriptor
access: modify
mechanism: by reference
Buffer having at least 32 bytes available to store password when
password_number argument value is -3.
17.3 – Description
The site can use this callback routine to interactively prompt
for passwords. The routine uses either the standard OpenVMS
password prompt or a prompt provided by the caller in the second
argument.
The password is returned in one of the following locations,
depending on the value of the password_number argument:
Value of Password_
Number Argument Location
0 or -1 LGI$A_ICR_PWD1
1 or -2 LGI$A_ICR_PWD2
-3 buffer argument
NOTE
This routine will do overstriking, if necessary, to support
echo local terminals. See the VSI OpenVMS Programming
Concepts Manual for more information about echo terminals.
17.4 – Condition Values Returned
SS$_NORMAL Success.
LGI$_INVPWD Password check failed.
LGI$_NOSUCHUSER No UAF record found.
18 – LGI$ICB_PWDEXPIRED
The LGI$ICB_PWDEXPIRED callback routine checks for password
expiration.
Format
LGI$ICB_PWDEXPIRED
18.1 – Returns
No value. Does not return on failure.
18.2 – Arguments
None.
18.3 – Description
Use this callback routine to determine whether the account
password has expired. If the password is expired, the callback
routine:
o Writes its standard error message to the user terminal, if
there is a terminal
o Does not return control to the caller
18.4 – Condition Values Returned
None.
19 – LGI$ICB_USERPARSE
The LGI$ICB_USERPARSE callback routine parses the user name
input.
Format
LGI$ICB_USERPARSE input_buffer
19.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
19.2 – Argument
input_buffer
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
The input buffer must contain the characters LOGIN in the first
five character locations, followed by an ASCII space character
and then the user name and applicable site-specified qualifiers.
19.3 – Description
The site can use this callback routine to parse input for
interactive logins on character-cell and DECwindows terminals.
Upon completion of this routine, the user name is accessible at
the LGI$A_USERNAME entry in the standard arguments vector.
19.4 – Condition Values Returned
True (1) if successful; otherwise, any condition code returned by
CLI$PARSE.
20 – LGI$ICB_USERPROMPT
The LGI$ICB_USERPROMPT callback routine prompts for the user
name.
Format
LGI$ICB_USERPROMPT prompt
20.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
20.2 – Argument
prompt
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
A string that must begin with "cr,lf". For example, to produce
the standard user name prompt, use your language equivalent of
the following BLISS value:
UPLIT(12,UPLIT BYTE(CR,LF,'Username: '))
Declare the string in C using the following statement:
$DESCRIPTOR(<variable_name>, "lrlnUsername:")
You then pass the descriptor using the variable name.
This routine also produces the standard user name prompt if you
pass the value 0 for this argument.
20.3 – Description
Use this callback routine to interactively prompt for the user
name on a character-cell terminal. The callback routine reads
the response to the prompt and does standard DCL parsing for the
user name and any qualifiers provided. Upon completion of this
routine, the user name is accessible at the LGI$A_USERNAME entry
in the standard arguments vector.
20.4 – Condition Values Returned
SS$_NORMAL Success.
LGI$_NOTVALID Retry count exceeded for user input.
21 – LGI$ICB_VALIDATE
The LGI$ICB_VALIDATE callback routine validates the user name and
passwords against the system authorization file.
Format
LGI$ICB_VALIDATE username ,pwd1 ,pwd2
21.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
21.2 – Arguments
username
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
User name.
pwd1
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
Primary password.
pwd2
OpenVMS usage:character string
type: string descriptor
access: read only
mechanism: by reference
Secondary password.
21.3 – Description
The site can use this callback routine to validate the user name
and the user's primary and secondary passwords against the system
authorization file (SYSUAF.DAT). The routine also:
o Updates the user authorization (UAF) record with information
about login failures
o Performs security auditing
o Performs break-in detection and intrusion evasion
21.4 – Condition Values Returned
Success, or an error indicating the reason for the failure.