LGI Routines
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help LGI Routines *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
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
are designed by site security administrators. The callback
routines are invoked by the callout routines.
| 1 - LGI$ICB_DISUSER |
The LGI$ICB_DISUSER callback routine checks the disabled user
account flag.
Format
LGI$ICB_DISUSER action
1.1 - Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
1.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
1.3 - Description
The site can use this callback routine to establish the standard
OpenVMS action if the DISUSER flag is set.
1.4 - Condition Values Returned
LGI$_DISUSER
SS$_NORMAL
| 2 - LGI$ICB_GET_INPUT |
The LGI$ICB_GET_INPUT callback routine enables interaction with
the user.
Format
LGI$ICB_GET_INPUT rab ,flags
2.1 - Returns
No value. Does not return on failure.
2.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).
2.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.
2.4 - Condition Values Returned
No return value. Examine status in RAB to determine the results
of the read operation.
| 3 - LGI$ICB_GET_SYSPWD |
The LGI$ICB_GET_SYSPWD callback routine validates the system
password.
Format
LGI$ICB_GET_SYSPWD
3.1 - Returns
No value. Does not return on failure.
3.2 - Arguments
None.
3.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.
3.4 - Condition Values Returned
None.
| 4 - LGI$ICB_MODALHOURS |
The LGI$ICB_MODALHOURS callback routine checks for restrictions
on access modes and access hours.
Format
LGI$ICB_MODALHOURS
4.1 - Returns
No value. Does not return on failure.
4.2 - Arguments
None.
4.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
4.4 - Condition Values Returned
None.
| 5 - 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
5.1 - Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
5.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.
5.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 OpenVMS Programming Concepts
Manual for more information about echo terminals.
5.4 - Condition Values Returned
SS$_NORMAL Success.
LGI$_INVPWD Password check failed.
LGI$_NOSUCHUSER No UAF record found.
| 6 - LGI$ICB_PWDEXPIRED |
The LGI$ICB_PWDEXPIRED callback routine checks for password
expiration.
Format
LGI$ICB_PWDEXPIRED
6.1 - Returns
No value. Does not return on failure.
6.2 - Arguments
None.
6.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
6.4 - Condition Values Returned
None.
| 7 - LGI$ICB_USERPARSE |
The LGI$ICB_USERPARSE callback routine parses the user name
input.
Format
LGI$ICB_USERPARSE input_buffer
7.1 - Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
7.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.
7.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.
7.4 - Condition Values Returned
True (1) if successful; otherwise, any condition code returned by
CLI$PARSE.
| 8 - LGI$ICB_USERPROMPT |
The LGI$ICB_USERPROMPT callback routine prompts for the user
name.
Format
LGI$ICB_USERPROMPT prompt
8.1 - Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
8.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.
8.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.
8.4 - Condition Values Returned
SS$_NORMAL Success.
LGI$_NOTVALID Retry count exceeded for user input.
| 9 - 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
9.1 - Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Condition value in R0.
9.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.
9.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
9.4 - Condition Values Returned
Success, or an error indicating the reason for the failure.
|
|
