The LGI$ICR_AUTHENTICATE callout routine authenticates passwords.

    Format

      LGI$ICR_AUTHENTICATE  arg_vector ,context

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 - 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.

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.

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.

5 - Associated OpenVMS Policy Function

    Perform standard password prompting and validation.