Logging in, part one

Logging in to UOS begins with a request to log in. There are only three possible sources of a log-in request: 1) A terminal, 2) a specially-crafted request sent over the network, or 3) programmatically via a created process - usually as a result of a batch job being started. Logins cannot be requested from any other device. For instance, a disk drive or DVDROM will never initiate a log-in request. We will discuss options 2 and 3 in the future - for now we will only consider logging in from a terminal. This process is handled by the LOGIN CUSP.

Most terminals are serial terminals and serial connections have two ends which have to be matched in their communication settings, such as speed. If the settings are mismatched, data will be corrupted between the two. We'd like to help with this by having the UOS end of the communication line automatically detect the speed and adjust. In theory, this is a simple algorithm. In practice, it is rather difficult due to variations in hardware. Serial line communications are not often used these days (with the possible exception of micro-factor computers such as the Raspberry Pi), and autobaud detection isn't usually needed for them when they are. We will address this at some point in the future, but for now we will ignore it. Note that in the case of a PC, the screen and keyboard comprise a virtual terminal that is directly connected and has no associated baud rate.

The LOGIN program is the first line of defense that UOS has against unauthorized users accessing the system. As such, it has to be designed to guard against malicious attacks. Understand that security through obscurity is a bad approach to protecting anything, but the less we give away, the harder it is for someone to break-in - or the longer it will take them. For this reason, unlike VMS (and many other operating systems) the LOGIN program will not display any kind of identifying header. When an operating system lets a user know which O/S it is, and which version it is, that is giving a lot of information out. It informs people what kind of constraints there are on user names and passwords, for instance. It also reveals which system vulnerabilities a given system has - especially it it is running an older version of the O/S. An experienced hacker is not going to be deterred by the lack of this information, of course, but it can slow down other people.

In addition, LOGIN will only allow so many failed attempts before it disconnects the user, slowing down brute-force attacks on passwords. It also doesn't validate the username until both username and password are provided by the user, and then simply indicates a general failure rather than indicating whether it was the username or the password that was wrong. Again this slows attackers down. These are things that VMS also does.

Of course, the greatest threat to any system's security is lax security by the users. There are many things we can do that help mitigate this (such as not giving users more privileges than they absolutely need). Some of these features are provided by LOGIN, in conjunction with UAF, such as multiple passwords, restricted hours of access, expiring passwords, captive accounts, and so forth. Other features are part of the UOS executive, such as file protection codes. We have discussed some of these things in the past, and we will discuss more in the future. For now, we will concentrate on the gatekeeper: LOGIN.

Many articles ago, we discussed how both the executive and the CUSPs together make up UOS: an operating system is more than just its kernel. I also mentioned that most program control flows from applications down into the executive. Callbacks work in the opposite direction. There are a limited number of CUSPs that are also called from the executive. One of these is LOGIN. The VMS program LOGINOUT is used both for logging in and logging out. Honestly, I don't know why. UOS has a different program for each operation, since there isn't much overlap in the code between them. Here is the user documentation:

Initiates an interactive terminal session.

Format

Ctrl/C
Ctrl/Y
Enter

Description

When Ctrl/C, Ctrl/Y, or Enter is typed on a terminal not associated with a process, the LOGIN program is run. The system prompts for the user name, and authentication (usually a password).
LOGIN performs the following functions:

Prompt for user name

Prompt for authentication

Validates user name and authentication

Sets process characteristics as per the UAF settings for the user

Start default shell, or the shell specified in the UAF, or the shell specified with /CLI

Execute the command file sys$system:login.com

Qualifiers can be specified immediately after the username.

Qualifiers

/CLI=shell name
Specifies the name of an alternate shell to override the default shell specified in the UAF for the user. The shell must exist in sys$system. The default shell is UCL.

/COMMAND=filespec
/NOCOMMAND
Specifies a command file to execute upon login. If none is specified, the default login command file is used. If /NOCOMMAND is specified, no login command file is used.

/DISK=device
The device specification to be associated with the SYS$DISK logical name for this session.

/NEW_PASSWORD
The user is prompted for a new password, as if the password had expired, before login can complete.

function Run : int64 ;

var Buf : array[ 0..1023 ] of char ;
    BufLen : int64 ;
    Cmd, NewPass : integer ;
    Command, Parameter : string ;
    DevFlags : int64 ;
    IOSB : TIOSB ;
    OS : POS_UOS ;
    Disk, Password, S, Shell, Temp : string ;
    Descriptor : array[ 0..1 ] of TDVI_Descriptor ;
    E, F : int64 ;
    Failures : integer ;
    List : array[ 0..5 ] of TSYS_Descriptor ;
    P : TPID ;
    CLI_Length : int64 ;
    DEV_Length : int64 ;
    DIR_Length : int64 ;
    CLI, DEV, DIR : string ;
    Flags : int64 ;
    Lastlogin : int64 ;
    Fails : int64 ;
    SRB, SRB1 : TSRB ;

label User_Prompt ;

begin
    // Setup...
    OS := new( POS_UOS, Init ) ;
    Result := 0 ;
    OS^.Outputln( '' ) ;  // One blank line to make sure we're not overwriting text
    Failures := 0 ;

As with Logout, and all CUSPs, the work of LOGIN is done via a Run procedure. Here we initialize the code and write a new line out to the terminal. This makes sure that we are past any previous text that might still be on the terminal.

    // Get usaername from terminal...
    P := OS^.PID ;
User_Prompt:
    Set_Echo( RH_SysCommand, True ) ;
    S := Get_Command_With_Timeout( 'Username: ', 9 ) ;
    E := LIB_Get_Exception( P ) ;
    if( E <> 0 ) then
    begin
        E := LIB_Get_Exception_Code( P, E ) ;
        if( E = SS_TIMEOUT ) then
        begin
            OS^.Outputln( '' ) ;
            OS^.Outputln( 'Error reading command input' ) ;
            OS^.OutputLn( 'Timeout period expired' ) ;

            // Kill process...
            SYS_DELPRC() ;
            OS.Free ;
            exit ;
        end ;
    end ;

First, we enable character echo so the user can see his username as he types it. It then prompts for the user name with a timeout. The reason for timeout is that as remote login requests are coming in, we don't want to have a bunch of idle processes running LOGIN waiting for a response from a remote user. So, after a period of 9 seconds of inactivity, we delete the process. Thus, a denial of service attack from the internet, for example, would only temporarily exhaust system resources or degrade performance. It also clears a physical terminal that has been abandoned mid-login.

A timeout ends an input operation, so when input returns, we have to check to see if there is a timeout error. If so, we tell the user and then delete the process. The code after SYS_DELPRC is technically not needed, but some emulators might not end a process at this point, so we exit nicely, just in case.

    // Parse switches...
    Shell := '' ;
    Command := '' ;
    Parse_Switch( 'CL|I', '', Command, Shell ) ;
    Cmd := Parse_Switch( 'CO|MMAND', 'NOCO|MMAND', S, Command ) ;
    Parse_Switch( 'D|ISK', '', S, Disk ) ;
    NewPass := Parse_Switch( 'N|EW_PASSWORD', '', S, Parameter ) ;
    if( ( NewPass = 1 ) and ( Parameter <> '' ) )  then
    begin
        OS^.outputln( 'Value not allowed - remove value specification' ) ;
        OS^.outputln( ' \NEW_PASSWORD=\' ) ;
        goto User_Prompt ;
    end ;
    Temp := Next_Switch( S, Parameter ) ;
    if( Temp <> '' ) then
    begin
        OS^.outputln( 'Unrecognized qualifier - check validity, spelling, and placement' ) ;
        OS^.outputln( ' \' + Temp + '\' ) ;
        goto User_Prompt ;
    end ;
    // At this point, S is the username...
    S := lowercase( trim( S ) ) ;
    Set_String( S, SRB ) ;

Next we process any switches specified after the user name, displaying an error if there is one that is unrecognized. Then we normalize the user name to lower case.

    // Get last successful login...
    fillchar( List, sizeof( List ), 0 ) ;
    Add_Item( 0, UAI_LASTLOGIN_I, int64( @LastLogin ), 8 ) ;
    SYS_GETUAI( 0, 0, SRB, int64( @List ), 0, 0, 0 ) ;

Next we look up the interactive login date/time for the specified user. We have to do this before we actually log in - if we look it up after logging in, we'll just get the current date/time. If the lookup fails due to the user not existing, the last login time (LastLogin) remains 0, indicating no previous log in.

    // Get password...
    Set_Echo( RH_SysCommand, False ) ;
    Password := Get_Command_With_Timeout( 'Password: ', 9 ) ;
    Set_Echo( RH_SysCommand, True ) ;
    E := LIB_Get_Exception( P ) ;
    if( E <> 0 ) then
    begin
        E := LIB_Get_Exception_Code( P, E ) ;
        if( E = SS_TIMEOUT ) then
        begin
            OS^.Outputln( '' ) ;
            OS^.Outputln( 'Error reading command input' ) ;
            OS^.OutputLn( 'Timeout period expired' ) ;

            // Kill process...
            SYS_DELPRC() ;
            OS.Free ;
            exit ;
        end ;
    end ; // if( E <> 0 )

Next we turn off the echo and prompt for the password, with a timeout. As with the user name, we kill the process if we time out.

    // (Try to) Log the user in...
    if( LOGIN( S, Password ) <> 0 ) then
    begin
        OS^.Outputln( 'User authorization failure' ) ;
        inc( Failures ) ;
        if( Failures > 4 ) then
        begin
            // Kill process...
            SYS_DELPRC() ;
            OS.Free ;
            exit ;
        end ;
        goto User_Prompt ;
    end ;

Next we call the LOGIN system service to log the user in. If it fails, we let the user know, increment the number of failures, and loop back to give them another chance if they made a mistake. However, if the user has tried unsucessfully five times, we give up and kill the process. This is to slow down potential brute force attacks from external threats. On success, the user is officially logged in.

    // Check allowed access dates/times...
    // TODO

    // At this point, the user is logged in...

    // Look up user info...
    fillchar( List, sizeof( List ), 0 ) ;
    ADD_Item( 0, UAI_DEFCLI_LENGTH, int64( @CLI_Length ), 8 ) ;
    ADD_Item( 1, UAI_DEFDEV_LENGTH, int64( @DEV_Length ), 8 ) ;
    ADD_Item( 2, UAI_DEFDIR_LENGTH, int64( @DIR_Length ), 8 ) ;
    SYS_GETUAI( 0, 0, SRB, int64( @List ), 0, 0, 0 ) ;
    setlength( CLI, CLI_Length ) ;
    setlength( DEV, DEV_Length ) ;
    setlength( DIR, DIR_Length ) ;

    fillchar( List, sizeof( List ), 0 ) ;
    ADD_Item( 0, UAI_DEFCLI, int64( PChar( CLI ) ), CLI_Length ) ;
    ADD_Item( 1, UAI_DEFDEV, int64( PChar( DEV ) ), DEV_Length ) ;
    ADD_Item( 2, UAI_DEFDIR, int64( PChar( DIR ) ), DIR_Length ) ;
    Add_Item( 3, UAI_FLAGS, int64( @Flags ), 8 ) ;
    Add_Item( 4, UAI_LOGFAILS, int64( @Fails ), 8 ) ;
    SYS_GETUAI( 0, 0, SRB, int64( @List ), 0, 0, 0 ) ;

    if( ( Flags and UAI_V_CAPTIVE ) <> 0 ) then // Captive account
    begin
        Disk := '' ;
        Shell := '' ;
        Command := '' ;
        Cmd := 0 ;
    end ;

We will skip the access dates/times until a future article. For now, LOGIN will not restrict logins based on that criteria. Next we get several pieces of information about the user. If the UAF flags indicate that this is a captive account, we clear all data that came from switches following the user name since they are not allowed in this context.

    // TODO: handle expired passwords, etc.

    if( ( Flags and UAI_V_DISRECONNECT ) = 0 ) then // Check for detached processes
    begin
        // TODO
    end ;

    if( ( Flags and UAI_V_DISWELCOME ) = 0 ) then
    begin
        OS^.Outputln( 'Welcome to UOS, Version ' + OS^.Version ) ;
    end ;
    if( ( LastLogin <> 0 ) and ( ( Flags and UAI_V_DISREPORT ) = 0 ) ) then
    begin
        OS^.OutputLn( 'Last interactive login on ' + ASCTIM( LastLogin, 0 ) ) ;
        if( Fails > 0 ) then
        begin
            OS^.OutputLn( 'Number of failures since last successful login: ' + inttostr( Fails ) ) ;
        end ;
    end ;

We will deal with expired passwords in the future when we deal extensively with authentication. We will also deal with detached processes in a future article. Next, unless it has been disabled, we display a welcome message. Also, unless disabled, we display the date/time of the last interactive login (if any), and how many login failures there have been since then.

    // Set up environment...
    if( Disk <> '' ) then // Disk override was specified
    begin
        Validate_Device( Disk ) ;
    end ;
    if( Disk = '' ) then // No disk override was specified
    begin
        Validate_Device( DEV ) ;
        if( DEV = '' ) then
        begin
            DEV := 'SYS:' ;
        end ;
        Disk := DEV ;
    end ;
    LIB_Set_Symbol( 'sys$disk:', Disk ) ;
    SRB.Length := length( DIR ) ;
    SRB.Buffer := int64( PChar( DIR ) ) ;
    SYS_SETDDIR( 0, SRB ) ;

Now we set up the environement for the user. First, we set the sys$disk logical to the default directory (either from the qualifier or the UAF). If a qualifier was specified, but the device isn't available or not a store, we ignore that and try the UAF-specified disk. It is possible that it is also unavailable, in which case we ultimately default to the public store. Then we set the default directory for that device.

    if( Shell <> '' ) then
    begin
        // Strip any location...
        E := pos( ':', Shell ) ;
        while( E <> 0 ) do
        begin
            Shell := copy( Shell, E + 1, length( Shell ) ) ;
            E := pos( ':', Shell ) ;
        end ;
        Shell := 'sys$system:' + Shell ;

        // Default the extension if not specified...
        E := pos( '.', Shell ) ;
        if( E = 0 ) then
        begin
            Shell := Shell + '.exe' ;
        end ;

        // Make sure the shell exists...
        SRB.Length := length( Shell ) ;
        SRB.Buffer := int64( PChar( Shell ) ) ;
        if( SYS_File_Exists( int64( @SRB ) ) <> 0 ) then // File not accessible
        begin
            OS^.OutputLn( 'Shell not found: ' + Shell ) ;
            Shell := '' ; // Use the default
            Command := '@sys$system:login.exe' ;
        end ;
    end ;
    if( Shell <> '' ) then
    begin
        CLI := Shell ;  // Use the shell specified in the switches
    end ;
    if( CLI = '' ) then // Use default shell
    begin
        CLI := 'sys$system:ucl.exe' ;
        Command := '@sys$system:login.com' ;
    end ;
    if( Cmd = 2 ) then // /NOCOMMAND
    begin
        Command := '' ;
    end ;

Next we determine which shell to use. The user can specify this with a switch after the user name, but if not specified (or not found), the UAF shell is used. If that isn't specified or the file isn't found, we default to UCL. Note that all shells (at least in terms of initial login) must reside in sys$system. Any other location is stripped from the name. The extension defaults to ".exe".

The user can also specify the initial command file as a switch after the user name. However, if they specify one along with an invalid shell, what they specify is ignored. By default the sys$system:login.com file is passed to UCL to do whatever custom login operations are desired by the system administrator.

    // Start the shell...
    SRB.Length := length( CLI ) ;
    SRB.Buffer := int64( PChar( CLI ) ) ;
    SRB1.Length := length( Command ) ;
    SRB1.Buffer := int64( PChar( Command ) ) ;
    F := RUN_SUPERVISOR ;
    E := LIB_RUN( int64( @SRB ), int64( @SRB1 ), int64( @F ) ) ;

    OS.Free ;
    SYS_EXIT( 0 ) ;
end ; // Run

We next run the shell, passing the RUN_SUPERVISOR flag to indicate that it should run in supervisor mode - as discussed in a previous article. Then we clean up and exit the program. The EXIT system service is how a program terminates normally. We will cover SYS_EXIT in the future.

    procedure Add_Item( Index, Code, BufAdd, BufLen : int64 ) ;

    var Ret : int64 ;

    begin
        List[ Index ].MBO := $FFFF ;
        List[ Index ].MBMO := -1 ;
        List[ Index ].Buffer_Length := BufLen ;
        List[ Index ].Item_Code := Code ;
        List[ Index ].Buffer_Address := BufAdd ;
        Ret := int64( @ResLen ) ;
        List[ Index ].Return_Length_Address := Ret ;
    end ;

This local function is used to fill out a system descriptor for the GETUAF calls.

    procedure Validate_Device( var Disk : string ) ;

    var E : int64 ;

    begin
        Temp := Disk ; // Save in case of error
        Disk := OS^.Get_Symbol( Disk ) ;
        if( Disk <> '' ) then // If symbol exists
        begin
            DevFlags := 0 ;
            BufLen := sizeof( Buf ) ;
            fillchar( Descriptor, sizeof( Descriptor ), 0 ) ;
            Descriptor[ 0 ].Buffer_Length := sizeof( DevFlags ) ;
            Descriptor[ 0 ].Item_Code := DVI_DEVCHAR ;
            Descriptor[ 0 ].Buffer_Address := integer( @DevFlags ) ;
            Descriptor[ 0 ].Return_Length_Address := integer( @BufLen ) ;
            GETDVIW( 0, 0, Disk, integer( @Descriptor ), integer( @IOSB ),
                0, 0, '', 1 ) ;
            E := LIB_Get_Exception( 0 ) ;
            if( E <> 0 ) then
            begin
                Disk := '' ; // Device not found or some more serious error
            end else
            if( ( DevFlags and DEV_V_MNT ) <> 0 ) then
            begin
                OS^.OutputLn( 'Device is not available: ' + Temp ) ;
                Disk := ' ' ; // So not "found" error isn't shown
            end else
            if( ( DevFlags and DEV_V_DIR ) <> 0 ) then
            begin
                OS^.OutputLn( 'Device is not file-structured: ' + Temp ) ;
                Disk := ' ' ; // So not "found" error isn't shown
            end ;
        end ;
        if( Disk = '' ) then
        begin
            OS^.OutputLn( 'Device not found: ' + Temp ) ;
        end ; // if( Disk <> '' )
        Disk := trim( Disk ) ;
    end ;

This local routine is used to verify that the passed device is a valid store. First we get the symbol value, then we use GETDVI to obtain information about the device. If the call fails, it is probably because the device doesn't exist, but it is possible that some other error occurred. In any case we clear the passed string if there was an error. Otherwise, we make sure that the device is mounted or clear the value and report the error. Next we check that the device is file structured or else we clear the value and indicate an error.

In the next article, we will cover the new system calls made above.