HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The information in this chapter is intended for programmers implementing the requirements of site security administrators or third-party security software producers.

This chapter differs from other parts of this book because it does 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.

14.1 Introduction to LOGINOUT

The OpenVMS login security program (LOGINOUT.EXE) supports calls to site-specific routines (LOGINOUT callout routines). These callout routines support custom login security programs such as smart card programs, pocket authenticator programs, and other alternative identification and authentication programs. The callout routines permit sites to combine portions of the LOGINOUT security policy functions with site login security functions to establish a customized login security environment.

14.1.1 The LOGINOUT Process

The site security administrator provides LOGINOUT with the following:

• One or more shareable images comprised of modules that include callout routines
• A list of the shareable images

As login events occur, LOGINOUT invokes the applicable callout, thus enabling the site to replace or augment each event using site-specific modifications.

The site may provide multiple callout images. The images are invoked in the order in which they are declared to the system. Each image contains an independently developed set of policy routines.

Each callout routine may do one of the following:

• Enforce site-specific policy functions
• Defer to subsequent routines
• Use elements of the standard OpenVMS policy functions

The following sections describe LOGINOUT's interaction with the external authentication policy supported by OpenVMS. For more information about single sign-on and user authentication, see the OpenVMS Guide to System Security.

Overview of External Authentication

At sites using external authentication, all authentication decisions for users are actually made by the LAN manager rather than OpenVMS; however, OpenVMS account restrictions and quota checks remain in effect.

To access the system, users must provide their LAN manager user ID and password at the login prompt. If local password synchronization is required, one of the following messages is displayed indicating the outcome of the synchronization attempt:

OpenVMS password has been synchronized with network password

Not able to synchronize OpenVMS password with network password

These messages can be suppressed on a per-user basis by setting the DISREPORT flag.

Specifying Local Authentication

The login command line supports the /LOCAL_PASSWORD qualifier. This qualifier indicates to LOGINOUT that the user intends to override external authentication by using their OpenVMS user name and password. This is considered a temporary means for logging in to the system when the external authentication service is unavailable. To use this qualifier, you must have SYSPRV privilege.

When a user has logged in locally, the following message is displayed:

Local logon successful; network logon service not used

Locally authenticated users are not subject to OpenVMS password policy, since the system manager specified that these users are subject to external authentication policy only.

14.1.3 The LOGINOUT Data Flow

Figure 14-1 provides an overview of the data flow between LOGINOUT, the callout routines, and site-specific shareable images that can include one or more callout modules.

Figure 14-1 LOGINOUT Callout Routines Data Flow

This section introduces the callouts that LOGINOUT uses to interface with the site-specific callout modules in the shareable images. The section also describes a set of callback routines that the callout routines can use to invoke services provided within LOGINOUT.

14.2.1 LOGINOUT Callout Routines

LOGINOUT calls a different site-provided callout routine at each important step in its execution. Table 14-1 briefly describes the LOGINOUT callouts. See Section 14.4 for detailed descriptions of these routines.

14.2.2 LOGINOUT Callback Routines

This section describes:

• The calling environment
• The callout routines and how they are organized and activated
• The callout routines interface

The general form for invoking the callout routines is as follows:

The call elements include the following:

• Standard argument vector: contains pointers to LOGINOUT data structures and callback routines for communicating with the user
• Context: a longword that the site-specific program may use to store a pointer to local context
• Routine-specific arguments: arguments directly related to the specific routine

A site may use several callout modules. For example, assume that the site is working with another program that uses logins or the site involves logins for various devices or logins at various security levels.

LOGINOUT invokes the callout routines using a vector of entry points rather than the routine name. Each vector entry point corresponds to a policy function, and the first vector entry contains a count of the entry points in the vector, thus making the vector extendable. Figure 14-2 shows how a callout routine vector is organized.

Figure 14-2 Callout Organization

Note that entry points may be accessed randomly. When a site-provided callout module does not provide a routine for a particular callout, the site must enter a 0 value as a placeholder into the corresponding vector location.

Callout modules may modify the vector during execution so that following events invoke different routines. For example, one of the initialization callout routines could modify the vector in anticipation of a following call to a different terminal or different job type, or it might zero the number of entry points to disable further calls to callout routines contained in the current callout module.

14.3.3 Activating the Callout Routines

A site activates the LOGINOUT callouts by identifying its callout images using the system executive-mode logical name LGI$LOGINOUT_CALLOUTS. The logical name may contain one value or a list of values that identify the callout images using either the:

• File name of a module located in SYS$SHARE:*.EXE
• Name of an executive-mode system logical name representing a full file specification

To protect against intrusion, the site uses the system parameter LGI_CALLOUTS to specify the number of callout images. If this value is nonzero and the supplied number of callout images does not correspond to the value, the login fails.

Sites that want to control their job creation process and authenticate each network login by implementing LOGINOUT callouts must set the NET_CALLOUTS system parameter to 255. This ensures that LOGINOUT is called for every network login --- bypassing any existing server processes.

The default value of NET_CALLOUTS (0) could bypass the LOGINOUT callouts and allow NET$ACP to perform its own proxy and login authentication. See the file SYS$SYSTEM:NETSERVER.COM for an example of how NET$ACP performs its own authentication and management of server processes.

Parameter values 1 to 254 are reserved by Compaq for future use.

Each image containing LOGINOUT callouts must define a universal symbol LGI$LOGINOUT_CALLOUTS. This symbol represents a vector of longwords that points to the entry points for the various callout routines, as shown in the following illustration:

The vector is headed by a longword count that delimits the number of callout routines supported by the callout module. Unused vector entries are identified by a 0 value.

Each callout routine has access to a vector of LOGINOUT internal variables, including the addresses of callback routines and other useful information. The vector entries are defined as offsets from the beginning of the vector. The vector has the following format:

Symbols of the form LGI$ICB_x are the addresses of the callback routines that the callout routines use to communicate with the user (see Table 14-2). Other offsets are addresses of useful variable information internal to LOGINOUT. These are described in Table 14-3.

The following C program illustrates the use of LOGINOUT callouts. The sample program changes the user name and password prompts to "Who are you?" and "Prove it." The program also adds the message "Goodbye." at logout.

#module LGI$CALLOUT_EXAMPLE "TOY LOGINOUT callout example"
/*
**++
**  FACILITY:
**
**      System help
**

** This program can be compiled with the following command
**
**   $ CC/STANDARD=VAXC/LIST/PREFIX_LIBRARY_ENTRIES=ALL LGI$CALLOUT_EXAMPLE.C
**
** This program can be linked with the following example command procedure
**
**    $ LINK/SHARE=LGI$CALLOUT_EXAMPLE SYS$INPUT/OPT
**    LGI$CALLOUT_EXAMPLE.OBJ

**    SYMBOL_VECTOR=(LGI$LOGINOUT_CALLOUTS=DATA)
**
** The following steps are used to install the program:
**
**    $ DEFINE/SYSTEM/EXEC LGI$LOGINOUT_CALLOUTS LGI$CALLOUT_EXAMPLE
**
** If the program is not located in SYS$SHARE, define it as follows:
**
**    $ DEFINE/SYSTEM/EXEC LGI$CALLOUT_EXAMPLE filespec
**
** [Remember that, without SYSNAM privilege, the /EXEC qualifier is ignored.]
**
**    $ INSTALL ADD LGI$CALLOUT_EXAMPLE
**    $ RUN SYS$SYSTEM:SYSGEN
**    SYSGEN> USE ACTIVE
**    SYSGEN> SET LGI_CALLOUTS 1
**    SYSGEN> WRITE ACTIVE
**
** The value of LGI_CALLOUTS is the number of separate callout images
** (of which this example is one) that are to be invoked.  If there is
** more than one image, the logical LGI$LOGINOUT_CALLOUTS must have a
** list of equivalence names, one for each separate callout image.
**
*/

/*
**
**  INCLUDE FILES
**
*/

#include descrip
#include rms
#include stsdef
#include ssdef
#include prcdef

/* Declare structures for the callout vector and the callout arguments vector */

struct LGI$CALLOUT_VECTOR  {
        long int LGI$L_ICR_ENTRY_COUNT;
        int (*LGI$ICR_INIT) ();
        int (*LGI$ICR_IACT_START) ();
        int (*LGI$ICR_DECWINIT) ();
        int (*LGI$ICR_IDENTIFY) ();
        int (*LGI$ICR_AUTHENTICATE) ();
        int (*LGI$ICR_CHKRESTRICT) ();
        int (*LGI$ICR_FINISH) ();
        int (*LGI$ICR_LOGOUT) ();
        int (*LGI$ICR_JOBSTEP) ();
        };

struct LGI$ARG_VECTOR  {
        int (*LGI$ICB_GET_INPUT) ();

        int (*reserved1) ();
        int (*reserved2) ();
        void (*LGI$ICB_GET_SYSPWD) ();
        int (*LGI$ICB_USERPROMPT) ();
        int (*LGI$ICB_USERPARSE) ();
        int (*LGI$ICB_AUTOLOGIN) ();
        int (*LGI$ICB_PASSWORD) ();
        int (*LGI$ICB_CHECK_PASS) ();
        int (*LGI$ICB_VALIDATE) ();
        void (*LGI$ICB_ACCTEXPIRED) ();
        void (*LGI$ICB_PWDEXPIRED) ();
        int (*LGI$ICB_DISUSER) ();
        void (*LGI$ICB_MODALHOURS) ();
        short *LGI$A_ICR_CREPRC_FLAGS;
        char *LGI$A_ICR_JOB_TYPE;
        char *LGI$A_ICR_SUBPROCESS;
        char *LGI$A_ICR_TERMINAL_DEV;
        struct dsc$descriptor_s *LGI$A_ICR_TT_PHYDEVNAM;
        struct dsc$descriptor_s *LGI$A_ICR_TT_ACCPORNAM;
        struct dsc$descriptor_s *LGI$A_ICR_CLINAME;
        struct dsc$descriptor_s *LGI$A_ICR_CLITABLES;
        struct dsc$descriptor_s *LGI$A_ICR_NCB;
        int *LGI$A_ICR_LOGLINK;
        struct dsc$descriptor_s *LGI$A_ICR_REM_NODE_NAM;
        struct dsc$descriptor_s *LGI$A_ICR_REM_ID;
        unsigned char *LGI$A_ICR_UAF_RECORD;
        struct RAB *LGI$A_ICR_INPUT_RAB;
        char *LGI$A_ICR_AUTOLOGIN;
        struct dsc$descriptor_s *LGI$A_ICR_USERNAME;
        struct dsc$descriptor_s *LGI$A_ICR_PWD1;
        struct dsc$descriptor_s *LGI$A_ICR_PWD2;
        int *LGI$A_ICR_PWDCOUNT;
        short int *LGI$A_ICR_NETFLAGS;
        };

globalvalue int LGI$_SKIPRELATED,       /* callout's return status */
                LGI$_DISUSER,
                LGI$_INVPWD,
                LGI$_NOSUCHUSER,
                LGI$_NOTVALID,
                LGI$_INVINPUT,
                LGI$_CMDINPUT,
                LGI$_FILEACC;


static int callout_logout();
static int callout_decwinit();
static int callout_identify();
static int callout_authenticate();

globaldef struct LGI$CALLOUT_VECTOR LGI$LOGINOUT_CALLOUTS =
                {
                9,
                0,                              /* init */
                0,                              /* iact_start */
                callout_decwinit,               /* decwinit */
                callout_identify,               /* identify */
                callout_authenticate,           /* authenticate */
                0,                              /* chkrestrict */
                0,                              /* finish */
                callout_logout,                 /* logout */
                0,                              /* jobstep */
                };

/* DECwindows initialization */

static int callout_decwinit()
    {
        /* Disable any further calls */
        LGI$LOGINOUT_CALLOUTS.LGI$L_ICR_ENTRY_COUNT = 0;
        /* Return and do standard DECwindows processing */
        return (SS$_NORMAL);
    }

/* Identification */

static int callout_identify(struct LGI$ARG_VECTOR *arg_vector)
    {

    int status;
    $DESCRIPTOR(wru,"\r\nWho are you? ");

    /* This example deals only with interactive jobs */
    if (!(*arg_vector->LGI$A_ICR_CREPRC_FLAGS & PRC$M_INTER))
        return(SS$_NORMAL);  /* Not interactive, do normal processing */
    if (*arg_vector->LGI$A_ICR_CREPRC_FLAGS & PRC$M_NOPASSWORD)
        return(SS$_NORMAL);  /* Invoked as logged in, don't prompt */
    if (*arg_vector->LGI$A_ICR_SUBPROCESS != 0)
        return(SS$_NORMAL);  /* Don't prompt on subprocesses */

    /* Check for autologin */

    if ($VMS_STATUS_SUCCESS(arg_vector->LGI$ICB_AUTOLOGIN()))
        return (LGI$_SKIPRELATED);       /* Yes, it's an autologin */

    if (!$VMS_STATUS_SUCCESS(status = arg_vector->LGI$ICB_USERPROMPT(&wru)))
        return (status); /* On error, return error status */

    /* Successful prompt and parse; skip OpenVMS policy */

    return(LGI$_SKIPRELATED);
    }

/* Authentication */

static int callout_authenticate(struct LGI$ARG_VECTOR *arg_vector)
    {

    int status;
    $DESCRIPTOR(proveit,"\r\nProve it: ");

    /* This example deals only with interactive jobs */
    if (!(*arg_vector->LGI$A_ICR_CREPRC_FLAGS & PRC$M_INTER))
        return(SS$_NORMAL);  /* Not interactive, do normal processing */
    if (*arg_vector->LGI$A_ICR_CREPRC_FLAGS & PRC$M_NOPASSWORD)
        return(SS$_NORMAL);  /* Invoked as logged in, don't prompt */
    if (*arg_vector->LGI$A_ICR_SUBPROCESS != 0)
        return(SS$_NORMAL);  /* Don't prompt on subprocesses */

    if (*arg_vector->LGI$A_ICR_PWDCOUNT != 0)
        /* This account has at least one password */
        if (!$VMS_STATUS_SUCCESS(status =
                        arg_vector->LGI$ICB_PASSWORD(0,&proveit)))
        return (status); /* On error, return error status */

    if (*arg_vector->LGI$A_ICR_PWDCOUNT == 2)
        /* This account has two passwords */
        if (!$VMS_STATUS_SUCCESS(status =
                        arg_vector->LGI$ICB_PASSWORD(1,&proveit)))
        return (status); /* On error, return error status */

    /* Successful prompt and password validation; skip OpenVMS policy */

    return(LGI$_SKIPRELATED);
    }

/* LOGOUT command */

static int callout_logout(username, procname,  creprc_flags, write_fao)
    struct dsc$descriptor_s *username, *procname;
    short *creprc_flags;
    void (*write_fao) ();
    {
        char *Goodbye = "   Goodbye.";          /* This will become an ASCIC */
        if ((int) write_fao != 0)               /* If output is permitted... */
        {
            Goodbye[0]=strlen(Goodbye)-1;       /* Fill in ASCIC count */
            write_fao(Goodbye);                 /* and write it */
        }
        return(SS$_NORMAL);
    }