HELPLIB.HLB  —  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
    (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.
Close Help