1 LGI_Routines 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. 2 LGI$ICB_DISUSER The LGI$ICB_DISUSER callback routine checks the disabled user account flag. Format LGI$ICB_DISUSER action 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Condition value in R0. 3 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 3 Description The site can use this callback routine to establish the standard OpenVMS action if the DISUSER flag is set. 3 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 3 Returns No value. Does not return on failure. 3 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). 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. 3 Condition_Values_Returned No return value. Examine status in RAB to determine the results of the read operation. 2 LGI$ICB_GET_SYSPWD The LGI$ICB_GET_SYSPWD callback routine validates the system password. Format LGI$ICB_GET_SYSPWD 3 Returns No value. Does not return on failure. 3 Arguments None. 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 Condition_Values_Returned None. 2 LGI$ICB_MODALHOURS The LGI$ICB_MODALHOURS callback routine checks for restrictions on access modes and access hours. Format LGI$ICB_MODALHOURS 3 Returns No value. Does not return on failure. 3 Arguments None. 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 3 Condition_Values_Returned None. 2 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 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Condition value in R0. 3 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. 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. 3 Condition_Values_Returned SS$_NORMAL Success. LGI$_INVPWD Password check failed. LGI$_NOSUCHUSER No UAF record found. 2 LGI$ICB_PWDEXPIRED The LGI$ICB_PWDEXPIRED callback routine checks for password expiration. Format LGI$ICB_PWDEXPIRED 3 Returns No value. Does not return on failure. 3 Arguments None. 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 3 Condition_Values_Returned None. 2 LGI$ICB_USERPARSE The LGI$ICB_USERPARSE callback routine parses the user name input. Format LGI$ICB_USERPARSE input_buffer 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Condition value in R0. 3 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. 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. 3 Condition_Values_Returned True (1) if successful; otherwise, any condition code returned by CLI$PARSE. 2 LGI$ICB_USERPROMPT The LGI$ICB_USERPROMPT callback routine prompts for the user name. Format LGI$ICB_USERPROMPT prompt 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Condition value in R0. 3 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(, "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. 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. 3 Condition_Values_Returned SS$_NORMAL Success. LGI$_NOTVALID Retry count exceeded for user input. 2 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 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Condition value in R0. 3 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. 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 3 Condition_Values_Returned Success, or an error indicating the reason for the failure.