Terminal Security System Technical Manual Prepared for Cargill Grain Lab Minneapolis, Minnesota by Cargill Grain Lab Computer Systems Group Jim Bostwick June 20, 1985 Sy42:[1,100]SCLIMAN.DOC CHAPTER 1 Introduction This is the technical support manual for the security CLI - SCLI. It contains module design information along with overall design guidelines. Additional information is provided for the use of maintainers of the program, includ- ing instructions for modifying passwords, response lines, protected terminals, and so on. A chapter describing modif- ications to the RSX system required by the security system is included, along with instructions for installing the changes. 1.1 Overview SCLI is a user-written command line interpreter, which provides additional access protection to one or more serial ports, beyond that provided by the RSX login procedure. The secure system consists of three 'components': the SCLI task itself, a modified RSX BYE program, and a patch to the RSX TT driver. The BYE modification causes BYE to determine if a pro- tected terminal is being logged off. If this is the case, BYE resets the CLI for that terminal to SCLI. The terminal driver patch prevents the driver from ar- bitrarily and unconditionally setting a remote port to MCR when the modem is answered. This is a two-line patch, and may be implemented using ZAP or OPEN/SAVE. These two modifications set up a situation where any protected port which is not currently logged on is under control of SCLI. SCLI then obtains all input to the pro- tected port. SCLI responds to the proper input by setting the port to MCR CLI, allowing the user to log on and use the system normally. This system has been designed to operate fully un- attended. It will be run at system startup, and never shut down. In fact, the system is very difficult to eliminate. CHAPTER 2 SCLI Narrative SCLI is a non-priveleged task. However, when installed as a CLI, SCLI takes on several normally priveleged attri- butes. SCLI implements access protection by simply sitting on the terminal(s), absorbing all input. When SCLI receives a valid password on a protected terminal, it gives control of the terminal to MCR, and remains 'quiet' until the termi- nal is logged off. At that point, BYE gives control back to SCLI, re-establishing protection. When SCLI is first started, normally just following system boot, it takes control of the protected terminals. As long as SCLI remains active (normally 'forever'), the protected terminals are in one of three states: protected, logged on, or disabled. A terminal is protected when SCLI is that terminal's CLI. A logged on terminal has already been 'admitted' to the system, and is in use by a valid user. A terminal can become disabled in the unlikely event that SCLI is shut down. In this state, no CLI is connected to the terminal, and it is effectively slaved. Note that this state occurs briefly during system shutdown, between the time that SHUTUP disables the CLI, and the time that shutdown completes. SCLI places terminals which it is protecting in one of two internal states: normal, and mumble mode. In normal mode, SCLI will accept a valid password, and give the user access to the system. In mumble mode, SCLI has detected unauthorized attempts to access the system; all input is treated as invalid, and the user will 'never' gain access to the system. Mumble mode is triggered by a preset number of sequen- tial invalid login attempts. Once in mumble mode, the (po- tential) user must wait a preset time interval before again attempting to log in. If the timer expires, and no input has been received, SCLI assumes that the villian has left, and a new user is attempting to gain access. On the other hand, if the user keeps trying, SCLI simply re-sets the timer, perpetuating mumble mode. SCLI maintains a log of all activity on both the Con- sole (CO: or COT), and the system error log file. The log to CO: is more detailed, since it is assumed that the con- SCLI Narrative Page 2-2 sole log will be purged more frequently than the error log file. SCLI is also sensitive to messages issued via the MCR CLI commands. There are currently three messages: two en- able/disable dumping of all invalid input to the console file. These are used for observing activity during attempt- ed break-ins to the system. The third message provides the only known means of shutting SCLI down while keeping the system running. NOTE This third message is known to a few programmers at the Grain Lab only. It is not to be made ava- ilable to Grain Lab staff in general, nor to plant staff under any circumstances. Should it be re- quired to provide plant staff with a shutdown me- chanism, another message should be defined for thier use. 2.1 SCLI Walkthru This section comprises a brief walkthrough of the SCLI task itself. Details of individual module action are conta- inied in subsequent chapters. SCLI is normally in a stopped state. Initialization is only performed at system startup, or following a program crash. Note that the RSX executive will automatically re- start SCLI as needed, so that the only truly fatal error is one which continually crashes SCLI. Initialization is brief, consiting of assigning a LUN (2) to the CO: device, and clearing out the user-id, and invalid counts for each protected terminal. Following initialization, SCLI lives in a loop which obtains a 'command' from the system (RSX), processes it, then loops. The executive will STOP SCLI until a command is available. Commands take two forms: user input, and messages. User input comes from one of the protected terminals. Messages come from the system, either automatically when events affecting SCLI occur, or in response to the MCR "CLI /MES" command. SCLI Narrative Page 2-3 The main code immediately determines if the 'command' is user input or a message. All message processing is done in subroutine DOMSG. User input is processed in the main SCLI module. All input is encrypted. The encrypted text is then compared against a command table, containing pre-encrypted, known commands. 2.1.1 Command Input Input commands are matched against the command table. The issuing tt is also determined and the corresponding entry in the tt-table is located. If no entry exists, the command is ignored (a log entry is made, however). Assuming the command comes from a known tt, the action taken depends upon two things: 1) the action specified in the command table (pass/fail); and 2) the current mumble status of the terminal. If the terminal is in mumble-mode, all input commands are treated alike: a 'random' reply is issued to the termi- nal, and the foo-count is incremented. If the terminal is not in mumble mode, commands with the ac.pas attribute cause SCLI to admit the user. Commands with the fail attribute (ac.fai), or those not found in the command table, cause the foo-count to be incremented, and the reply message from the table issued to the terminal. If, after incrementing, the foo count exceeds the pre-defined MAXFOO, MBLON is called to place the terminal in mumble mode. SCLI admits a user to the system by first clearing the foo-count, and total-foo, saving the user-id in the tt- table, marking the terminal as 'logged on', and issuing a SCLI$ directive to set the terminal to MCR. This gives the user access to the standard RSX login procedures. 2.1.2 Mumble Processing Mumble mode simply means that no input from the termi- nal will be accepted as a valid password. Mumble mode is triggered by a number of invalid commands which exceeds the MAXFOO limit. It is terminated by a timer. Once in mumble- mode, any command input causes mumble mode to be perpetuat- ed. Only if the terminal is 'quiet' (e.g., no commands received by SCLI from that terminal) for a predetermined time will mumble mode be reset. This is handled in module SCLI Narrative Page 2-4 MUMBLE, which contains the MBLON initiator routine, and MBLAST, the timer service routine. When mumble mode is entered, a timer is started, with MBLAST specified as the entry point. Since several terminal may be in mumble mode at one time, the terminal is identi- fied by a unique event flag. When the timer expires, MBLAST is entered, and retrieves the EFN number form the stack. The EFN is located in tt-table, which gives access to the foo-count. If the foo-count is zero, MBLAST resets the mum- ble bit for that tt, and exits. This clears mumble mode, allowing the next valid password to be accepted. On the other hand, if the foo-count is non-zero, MBLAST adds the count to the total-foo (for logging purposes), cle- ars the foo-count, and re-issues the mark-time directive. This perpetuates mumble mode for another interval. 2.1.3 Message Processing Messages are key to SCLI - as they inform the CLI of system actions which might affect terminal security. Several operator-initiated messgaes are also accepted, which control SCLI functions. SCLI makes great attempts to maintain it's control over protcted terminals. Basic protection is provided by the op- erating system. All input to a terminal goes to that termi- nal's CLI, without exception (the standard control characters like CTRL-U, -S, etc. continue to be processed by the tt driver). Also, a CLI is non-abortable - it must be first eliminated before the task can be aborted. Finally, if the CLI task exits for some reason (such as fatal error), the executive will re-activate it when a mes- sage or command is received for that CLI. This more or less makes SCLI a crash-proof program. SCLI is allowed to die on rare errors, such as low-pool conditions, without compromiz- ing security. A cli may only be eliminated if no terminals are linked to it. SCLI goes beyond this protection by reacting to the 'you have been eliminated' message with a RPOI of MCR to re- establish the cli. This occurrs very rapidly, providing good security (not perfect) against a fast typist's 'elimi- nate, abort' sequence. The MCR SET command may be used (from a priveleged, logged-on terminal), to alter the CLI associated with a ter- minal. SCLI reacts to this as well. If a protected termi- SCLI Narrative Page 2-5 nal which is not known by SCLI to be 'logged on', is reset to a different CLI, SCLI simply sets the terminal back to SCLI with the SCLI$ directive. .hl 2 User Messages There are currently three messages known to SCLI, bey- ond the system-initiated ones. THese are all issued via the MCR CLI /MESSAGE directive. Two messages set and reset 'verbose' logging. Verbose logging is normally OFF (reset). When set, all invalid input to scli is passed on in a log entry. When reset, only the invalid command causing mumble- mode to be initiated is so logged. The third user message provides the only known means to effect the orderly shutdown of SCLI. When issued, this mes- sage sets a flag, telling SCLI to accept normally unfriendly behavior such as terminal CLI reassignment, and CLI elimina- tion. Note that, even though this 'maintenance shutdown' mode is set by the message, security protection remains in effect until the user disconnects SCLI from the protected terminals, and elimintates SCLI. 2.1.4 Logging Module LOG handles all logging functions. A macro, de- fined in SCLIDAT.MAC, eases the setup and call of LOG. All logging is via pre-defined messages, with variable parame- ters. The DOLOG macro accepts the message number and a message-specific parameter list. Messages may be routed to either the console (device CO:), or to the system error log file, or both. Message routing is controlled by flag bits in the message definition (module LOGMSG.MAC). The RSX $EDMSG routines are used to format the messages, handling all conversion and parameter substitution. Since messages are routed through CO:, logging is de- pendent upon the settings of the console output task (COT). Using the MCR SET /COLOG commands, it is possible to route console messages to a terminal, a file, or both. If COT is turned off entirely, messages will appear on the system con- sole device. A later chapter covers the format and content of all log messages in full detail. CHAPTER 3 Standards 3.1 Coding standards This section presents coding and design standards to be followed for this project. 3.1.1 Modularity This is a fully modular program. Each source file must contain code for a single function. This may include sever- al related subroutines, or a single routine. An example of the former might be the MUMBLE.MAC module, containing MBLON, MBLOFF, and MBLAST -- all routines relating to initiating and terminating mumble mode. It would also be acceptable for these three routines to exist in separate source files. 3.1.2 Source Format Each source module will be maintained in a SourceTools archive (xxx.SCN file). File TEMPLATE.MAC will be used as the basis for all source files. The fields surrounded by tilde characters (~) are supplied by GETSRC, and should not be altered. There will be a module header for each routine. The skeleton header is provided by the CTRL-P command, assuming the system edt include file "MACRO" is used. The header shall contain the module title, a description of its func- tion, call site, input and output parameters, and register usage. A list of routines called will be included. The description will include the module's function, error re- turns, and algorithm if not self-evident. 3.1.3 Source Control This project is being implemented under the SourceTools system. Every source file will be under "SrcCon" control. New modules are to be entered into the system following ini- Standards Page 3-2 tial test. Subsequent modifications are to be under source control. Test programs will also be subject to the same controls. 3.1.4 Test Programs Most modules will have an associated test program, which demonstrates the module functions. Test programs need not exhaustively test the module, and should be as simple as is reasonable. Extensive testing will be done during integ- ration. Individual test programs may exercise multiple modules, so long as it remains easy to determine the source of faults. Test programs which evolve to test several related modules are ideal. 3.1.5 PSECT Usage This section defines the PSECT (program section) usage for the project. 1. BLANK - all program code will reside in the blank (default) psect. 2. GDATA - global common data (rw, gbl, ovr). This psect defined by module SCLIDAT, which must be in- cluded in the assembly of using modules. 3. DATA - global private data (rw, gbl). 4. LDAT - local data. This psect shall be used by mo- dules for scratch storage - assume that it will be destroyed across module invokations. 5. DPBS - static directive DPBs - (rw, lcl) Except for GDATA, each module may contribute to these psects. Data which is shared among modules must be defined in SCLIDAT.MAC. Psect DATA is global, concatenated, and may be used by any module which needs data to remain across calls to the module. Psect LDAT is overlaid and is to be used for scratch storage. The contents of LDAT are undefined upon entry to a module. Standards Page 3-3 NOTE Any program contributing to one of the data psects must include an .EVEN directive following defini- tions for the psect. This forces each module's contribution to be of even size, and prevents er- rors due to TKB's byte alignment of data psects. 3.1.6 Exceptions The only exceptions to the above standards are the mod- ifications to DEC system software. These modifications, to module TTMOD.MAC of the RSX terminal driver, and to BYE.MAC, shall adhere to the format and standards employed by DEC in constructing and maintaining RSX system software. Note that these modules stand alone from SCLI, even though the modi- fied programs are required for proper function of the secu- rity system. Modificatons to TTDRV and BYE are documented in later chapters. The related files (including separate runoff source files for each modification) are found in uic [1,101] (11MPLUS and common) and [1,102] (11M specific) on the SCLI sources disk. CHAPTER 4 Database This chapter describes the database used by SCLI. The database consists of global data defined in module SCLIDAT, internal error messages defined in ERNUM.TXT (these are im- plicit in the SCLI code), logging messages defined in LOGMSG.DAT, and the command table, defined in KEYTAB. These are all internal databases - SCLI does no file operations of it's own. 4.1 Global Data Module SCLIDAT defines the global data for SCLI. This module must be included ( .include directive) in all source modules which must access the global database. 4.1.1 Constants A number of constants are defined. Most of these de- fine the offsets and flag bit values for the tt-table, and the command table. Three additional constants tune the mumble-mode functions. * MAXFOO sets the trigger point for mumble mode. When more than maxfoo invalid commands are received, mum- ble mode is entered. This should remain a fairly small number (3-5). * MBLUNI defines the time units for the mumble inter- val timer. This must have a value of 2 (seconds) or 3 (minutes). * MBLTIM defines the count for the mumble interval timer. A time interval of 2-5 minutes is suggested. 4.1.2 TT-TABLE This table contains one entry per protected terminal. It must be terminated with a zero word. Macro DEFTT, also defined in SCLIDAT, is used to construct the table. A table entry contains the following fields: Database Page 4-2 * tt.num - integer number of the terminal * tt.foo - integer count of invalid commands This value is incremented for each invalid com- mand received from the terminal. It is reset by the mumble timer completion routine (MBLAST). This value must remain zero for an entire mumble interval before MBLAST will reset mumble mode. * tt.efn - event flag used in mumble-mode for this terminal * tt.flg - flags word tt.flg bits are: * fl.mbl - 1-> terminal is in mumble mode * fl.pro - 1-> this terminal's cli is currently SCLI * tt.uid - pointer to user-id string, or nil This pointer is initialized when a user is ad- mitted to the system. It is then used when the use loggs out (SCLI resumes control over the terminal), to write a log entry. * tt.tot - integer total foo count since last login This value is maintained entirely for logging purposes. Since tt.foo is reset at the end of each mumble interval, tt.tot is used to accumulate the total number of invalid login attempts. This value is cleared when a user is admitted to the system. 4.1.3 Command Table There are two command tables in SCLI. The pre- encrypted command strings are in a table defined locally to the LOOKUP subroutine. Lookup returns an index into this table, or zero if no entry is found. The command table defined in SCLIDAT contains corres- ponding entries. The index returned by LOOKUP is used to access CMDTBL. Cmdtbl is also zero terminated, and constant MAXCMD also gives the address of the end of table. Currently, only MAXCMD is used. The fields of cmdtbl are as follows: * cm.rpl - pointer to reply string The reply string is issued to the user's termi- nal when this command is input, and the terminal is NOT in mumble mode. Database Page 4-3 * cm.id - pointer to the plain-text user id string. This string is only defined for commands which are valid passwords. When the user is logged on, the user-id string is used to greet the user, and is en- tered in a log entry. The user-id is also saved in the tt-table, and appears in a logout message when SCLI resumes control of the terminal. * cm.act - the action to be taken when this command/message is received. There are two actions only for command input: ac.fai and ac.pas. They are fail/pass respectively. The presence of a fail action allows dummy table entries. Most often these are used for common login sequences such as HEL, LOGIN, etc. This allows non-standard replys to be issued for these commands. AC.MES defines the first message entry. Actions greater than or equal to ac.mes are by de- finition messages received via the CLI /MESSAGE fa- cility. The first such message has the same commmand number as ac.mes. Three messages are de- fined at this time: ac.mai enables maintenance shutdown mode; ac.vrb enables verbose logging of in- valid input; ac.qui disables verbose logging. The first entry in cmdtbl is required to be the unknown-command action. Unknown commands, commands from non-protected terminals, and mumble-mode all use the reply string from this entry. Other entries in the table may be in any order, al- though by convention the message entries are grouped at the end of the table. 4.1.4 Reply Strings These are simply ASCIZ strings which are pointed to by the command table entries. There need not be a one-one cor- respondence between the number of such strings and the number of command table entries. The reply string for a valid login command should be some sort of greeting to the user. Other reply strings are up to the programmer. Database Page 4-4 4.1.5 User-id Strings These are plain-text identifiers for each valid user of the system. They are placed in log entries at login and lo- gout (to and from SCLI) time. 4.1.6 Global Variables Several variables are defined in SCLIDAT, which are used globally. Their use is fairly obvious. One is the Flags word, consisting of two flag bits which configure SCLI. GF.KIL is the maintenance shutdown bit. It is set when the ac.mai message is received by SCLI, and disables several protection features. When set, it it possible for the knowlegable user to shut down SCLI in an orderly manner. When clear, it is essentially impossible to shut SCLI down other than by pathological means. The other flag bit is GF.VRB, which controls the ver- bose logging of invalid input commands. 4.2 Internal Errors Internal errors are logged through the same logging me- chanism (DOLOG) used for other activity. Log message number 9. signifies an internal error log entry. Because parame- ters must be passed by reference, some care is required in setting up an internal error log entry. A typical internal error call is as follows: mov $dsw, p1 mov 1, nparm mov 5, err DOLOG 9., where p1, nparm, and err are all variable labels. Note that the number of parameters beyond nparm is variable. Nparm tells the log routine how many parameters to include in the log entry, and how many to pull off the R5 stack. Err and nparm themselves are always required, and are NOT counted in the value of nparm. Due to limitations on log entry size, only the error number and parameter values are logged. File ERNUM.TXT, re- produced in an appendix, gives the error numbers, initiating routine, number of parameters, and their meaning. Using the above example, error 5 is issued by SCLI upon failure to in- Database Page 4-5 itialize (ALUN$) the console LUN. P1 is the directive status word. 4.3 Log Messages Log messages are defined in module LOGMSG.MAC. For each message, an ASCIZ string is defined, which is used as the 'control string' in an EDMSG call. See the RSX System Library Reference Manual for the format and functions of the EDMSG routines. Two other structures are associated with the log mes- sages. Table msgtbl contains the pointer to the ASCIZ con- trol string for each message. The strings are accessed by using the message number as an index into msgtbl, from which the string address is retrieved. The other table, MSGFLG, is a byte table containing control bits for each message. It is also indexed by the message number. The control bits specify the desitination of the message - the console, error logger, or both. A prefix (PREMSG) is added to each log entry. Currently , the prefix consists of the word "SECURE:" only. 4.4 Key Table For security reasons, the text of commands and messages is stored internally in encrypted form. Input to SCLI is then encrypted using the same algorithm, and the scrambled text compared against the internal tables. Module LOOKUP performs the encryption and table lookup functions. It 'includes' module KEYTAB.MAC, which defines the table. KEYTAB.MAC is in turn produced by program KEY- GEN, which takes input file KEYTAB.TXT (the plain text mes- sages), encrypts the text, and writes KEYTAB.MAC as it's output. KEYTAB.MAC defines a table of pointers to ASCII strings. The table entries must correspond to the entries in CMDTBL (defined in SCLIDAT). It is critical that their be a one-one correspondence between KEYTAB and CMDTBL. That is, each entry in CMDTBL must have a corresponding entry in KEYTAB, and vice versa. If these two tables are not confor- mant, SCLI will fail in various and often obscure ways. CHAPTER 5 Maintenance Instructions This chapter contains sections devoted to rebuilding and modifying SCLI. It will make reference to the USRSB routine and the modified BYE program, both of which are more fully described in a later chapter. Also found in a later chapter are details of required modifications to the RSX terminal driver. Maintenance functions for SCLI primarily resolve into three areas: protected terminals, passwords, and users. These areas can be expected to change for each installation. 5.1 Protected Terminals The number and identity of terminals protected by SCLI is coded in two areas: first in the tt-table in SCLIDAT.MAC; second, in the USRSB module included in the modified BYE program. It is necessary that both these mo- dules define the same terminals. 5.1.1 USRSB USRSB contains a table (JMBTBL) with an entry for each protected terminal. The entry consists of the terminal number (an integer), and the default CLI name (in RAD50). Macro ENT defined in USRSB.MAC will construct a correct table entry. It is normal to leave several empty entries in the table. Having empty entries allows the table to be mod- ified using ZAP, without having to rebuild the BYE program. BYE ignores any null entries in the table. While it is necessary that each terminal protected by SCLI have an entry in JMBTBL, it is possible to use the same mechanism to change the default CLI for other (non-secure) terminals. Thus, JMBTBL may have additional entries, refer- encing CLIs other than SCLI. Such entries will not effect security operations. Whenever a terminal logs off (using the BYE program), BYE checks the table for a terminal number match. If a match is found, BYE forces the CLI to that given in the table. The effect is to have the CLI for that Maintenance Instructions Page 5-2 terminal as other than MCR whenever the terminal is logged off. 5.1.2 SCLIDAT As previously described, SCLIDAT defines TTTBL, which has an entry for each protected terminal. It is necessary that any terminal with the default CLI of SCLI have an entry in TTTBL. If a mismatch between TTTBL and JMBTBL occurs, either the CLI will not be re-established on logout, or SCLI will never allow access through the terminal. In the latter case, SCLI will issue an error message "Message from unknown terminal". It is possible to alter TTTBL using ZAP, but the normal mode will be to rebuild SCLI after editing SCLIDAT. 5.2 Passwords Passwords are defined by KEYTAB.TXT. These are ASCII strings, up to 72. characters in length. The key strings may contain any printable character (including tab), and some control characters (those which are not intercepted by the terminal driver). CASE IS SIGNIFICANT! Unlike the MCR interface, which automatically converts input to upper case, the SCLI interface accepts upper or lower case. This fact should be used in designing passwords. Passwords should be phrases, and should be at least 10- 12 characters in length. To alter a password, edit KEYTAB.TXT to define the ap- propriate plain-text string. Recall that the entries in KEYTAB correspond to the command table entries in SCLIDAT. Once KEYTAB.TXT is as desired, run program KEYGEN. The nor- mal command to KEYGEN is: KGN>KEYTAB.MAC=KEYTAB.TXT KEYGEN will write the output file containing the encrypted text strings. For further information on KEYGEN, see the source file KEYGEN.MAC. Once KEYGEN.MAC has been created, reassemble module LOOKUP, which is the only module to include KEYTAB. Then, rebuild SCLI. Maintenance Instructions Page 5-3 NOTE All that is really required is the edit of KEYTAB.TXT. Then, use the MAKE program to rebuild SCLI. MAKE will detect the new KEYTAB, run KEYGEN (rebuilding IT if necessary), and rebuild SCLI. 5.3 Command Table The command table in SCLIDAT defines the known com- mands, and the action to be taken. Probably the most fre- quent alterations will be to the uiser-id strings. Again, it is necessary to maintain a correspondence between the entries in CMDTBL and those in KEYTAB. 5.4 Summary This section summarizes the required edits to effect various configuration changes to SCLI. 5.4.1 Change Terminals To alter the protected terminals, JMBTBL in USRSB and TTTBL in SCLIDAT must be modified. Rebuild BYE and SCLI. 5.4.2 Change Passwords To alter password text, for either input commands or messages, edit module KEYTAB.TXT. Then, run KEYGEN to cre- ate KEYTAB.MAC. Reassemble LOOKUP, then rebuild SCLI. 5.4.3 Change Users To change a user's id string, edit the string in SCLI- DAT, and/or the string pointer in CMDTBL, also in SCLIDAT. Rebuild SCLI. To add or remove a user, edit CMDTBL in SCLIDAT, possi- bly adding a user-id string. Edit KEYTAB.TXT to maintain correspondence between password strings and command table Maintenance Instructions Page 5-4 entries. To rebuild, follow instructions above for changing passwords. 5.4.4 Change Messages The procedure for adding or modifying messages is es- sentially the same as that for user-ids, as described above. The message text is in KEYTAB, while the corresponding com- mand table entry is in SCLIDAT. 5.5 Build Instructions SCLI is composed of three components: the SCLI task itself, the modified BYE task, and the modified TTDRV driver. Each is built in a separate operation. For most maintenance operatons, it will not be necessary to rebuild all three components. SCLI will normally be installed by copying the source kit to the SYSGEN work disk for the target system. If ne- cessary, copy all files in uic [1,100], [1,101], and [1,102] from the SCLI kit to the target disk. The following discus- sion assumes that these accounts do in fact exist on a sys- gen work disk. The process is similar for other source locations. It is also assumed that required modifications to the sources have been made, and the archive (.scn) files updat- ed. 5.5.1 SCLI SCLI rebuild is controlled by the sourcetools MAKE pro- gram. Use of MAKE greatly simplifies the rebuild process. To rebuild SCLI, enter the following MCR commands: 1. SET /UIC=[1,100] 2. @MAKE SCLI When the command file completes, copy SCLI.TSK to the library account on the target system disk. Maintenance Instructions Page 5-5 5.5.2 Documentation SCLI documentation can be rebuild manually from the ar- chive files. Simply GET the required modules and pass them through RNO. A full documentation set may be built with the following MCR commands: 1. SET /UIC=[1,100] 2. MAK SCLIDOC.CMD=SCLI/target:"Dockit" 3. @SCLIDOC.CMD Be warned that some of the runoff source files include (.require) additional runoff sources. Users unfamiliar with the sources should either rebuild the entire kit, as des- cribed above, or examine the source files to ensure that the required include files are present. Individual documents may be rebuilt by substituting their name for the 'target' above. For example /target:"Scliman.doc" would produce this manual. 5.5.3 BYE BYE is built in [1,101] (M+) or [1,102] (M), and copied to the library account of the target disk. BYEASM.CMD will assemble BYE. USRSB is reassembled as follows: GET USRSB MAC USRSB,USRSB=USRSB TKB @BYE2BLD will rebuild BYE2.TSK. BYE2BLD assumes that device TK: points to the sysgen work disk (to obtain RSX11M.STB, MCR.OLB, etc), and that BYE.OBJ and USRSB.OBJ are in the current account. It leaves BYE2.TSK and BYE2.MAP in the current account. 5.5.4 TTDRV The terminal driver modification is not automated. Normally, the modified source file will be copied from [1,101] (or [1,102]) into [11,10] of the sysgen disk prior to SYSGEN. SYSGEN then builds the modified driver by de- Maintenance Instructions Page 5-6 fault. If the modification must be done after SYSGEN, the following instructions should be followed for MPLUS. The procedure for M is similar. 1. Copy TTMOD.MAC and TTMODASM.CMD from [1,101] to [11,10]. 2. Execute MAC @TTMODASM, from [11,10]. 3. From [1,24]: LBR TTDRV/RP=[11,24]TTMOD. 4. From [1,24]: TKB @[200,200]TTDRVBLD 5. Use VMR to UNLoad the old driver and LOAd the modi- fied one. 5.6 Initialization SCLI should be installed with the CLI=YES option either in VMR or STARTUP.CMD. Very early in STARTUP.CMD, file STARTSCLI.CMD should be executed. Logons should be disabled until after STARTSCLI is executed. Alternately, SCLI may be initialized directly from STARTUP.CMD, using STARTSCLI as an example of the commands. It is important that the proper switches be included in the CLI command initializing SCLI. If "/QUI/MES/LGO" are not present, the security system will not function properly. In most cases, the protected terminals will become unusable (usually slaved). The prompts may be changed as desired. CHAPTER 6 Module Descriptions This chapter contains a section for each module in the system, excepting test programs. The information in these sections is essentially a duplicate of the header informa- tion in the source module. 6.1 Global Data Module SCLIDAT defines the global database for the SCLI program. This file is "included" (.INCLUDE or in assembly command line) in any source program which requires access to the global data. Note that many modules do not require ac- cess to the global data. 6.2 CRYPT Crypt performs a simple, in-place encryption of the input string. The algorithm is the familiar and relatively inse- cure XOR of data bytes with a key text. This works for crypt because the key is guaranteed to be longer than the input text, and the messages are relatively short. Both combine to frustrate normal breaking techniques. If r0 is odd, the first character of the key is skipped, resulting in word alignment for most of the routine. CALL jsr pc,CRYPT INPUT r0 -> input string r1 = length of input string OUTPUT input string encrypted in place REGS all preserved Program TSCRYPT exercises this routine. Module Descriptions Page 6-2 6.3 DOMSG DOMSG processes all messages (as opposed to commands) re- ceived by SCLI. Messages come in two forms: those produced automatically by RSX, and those initiated by someone using the MCR "CLI /MESSAGE" command. Both types are important to SCLI. CALL jsr pc, domsg INPUT r0 -> GCCI command buffer OUTPUT various (including immediate exit) depending upon message received. REGS preserved Module Descriptions Page 6-3 6.4 LOG LOG logs messages to the error logging file (via SMSG$) and/or to the console (CO). For testing, if logtt3 is de- fined (just before entry point), logs all messages in raw form to LUN 3, which is hardcoded to TT3. Messages are identified by number. A variable number of parameters are required depending upon the message. For message numbers, required parameters, see module LOGMSG.MAC. Message number is a pass-by-value. All of the variable params are pass by reference. CALL call r5,log, msg = message number (messages defined above) params = parameters dependant upon message number see individual message definition above INPUT params on r5 stack OUTPUT message formatted and logged as indicated by flags word in message database (defined above) REGS preserved CALLS uses $EDMSG from SYSLIB to format messages includes LOGMSG.MAC to define messages 6.4.1 Notes LOG does a QIO no-wait to CO:, followed by a mark-time. Both specify AST routines. Whichever one completes first cancells the other. This provides output timeout services, since a hung QIOW to CO: would hand the entire SCLI system. LOG also contains code to fake out a call to itself in the event of an internal error. This code is a bit wierd, in that it must protect against infinite looping on multiple errors. However, it is known to work. Module Descriptions Page 6-4 6.5 LOOKUP LOOKUP is called with a plain-text command line. It first encrypts the command line, then searches the password table for a match. LOOKUP returns the offset of the match- ing entry in the command table, or 0 (zero) if no matching entry exists. Also, a no-match condition returns carry set. NOTE The returned index is the byte offset into the command table (NOT the password table). The pass- word table contains one less entry (the entry with index=0) than the command table. In simple terms, add the base of the command table to r2 on return and look at the command. CALL jsr pc, lookup INPUT r0 -> command line r1 = length of command line OUTPUT r0 -> same command line, but encrypted now r2 = command index (0 -> no match) carry set -> no match carry clear -> match found REGS r2 modified, string referenced by r0 modified others preserved CALLS CRYPT NOTES: 1. In order to work properly, trailing whitespace (tab or space) should be stripped from command line. Leading whitespace is ok, allowing tricky passwords like hi there! 2. Source module KEYTAB.MAC is .INCLUDED in this mo- dule. It is generated by KEYGEN. Program TSTLOOKUP exercises this module. Module Descriptions Page 6-5 6.6 MUMBLE Module MUMBLE.MAC contains two routines: MBLON and MBLAST. Together these routines implement mumble mode ser- vices. MBLON initiates mumble mode for the current tt. The current tt is pointed to by ttptr (defined by sclidat). CALL jsr,pc mblon INPUT ttptr -> tt record to be put in mumble mode OUTPUT tt placed in mumble mode, foo-count added to total for tt foo-count for tt cleared mumble-timer started for tt's efn REGS preserved MBLAST is entered upon expiration of the mumble-timer for a given tt. The associated tt is determined, and it's foo-count examined. Either the mumble-timer is perpetuated, or the tt is kicked out of mumble-mode. CALL AST service routine INPUT on stack: efn (remove before exit) OUTPUT if tt.foo > 0 mumble-timer restarted if tt.foo = 0 mumble-mode cleared in either case tt.foo added to tt.tot, then cleared REGS preserved Module Descriptions Page 6-6 6.7 SLEN SLEN determines the length of an asciz string. ASCIZ strings are terminated by a null (zero) byte. Length re- turned does not include the null byte. CALL jsr pc, SLEN INPUT r0 -> input string OUTPUT r0 -> input string length on stack REGS all preserved NOTE: 1. Caller must pop length off of stack on return 2. Input string had better have a null terminator! Program TSTSLEN exercises this routine. Module Descriptions Page 6-7 6.8 TYPE TYPE outputs a message to one of two terminals: the CLI command input terminal, or the task ti:. The latter is assumed pointed to by LUN 5. For the former, the terminal is in the GCCI buffer pointed to by r0, and LUN 1 is as- signed to that terminal. TYPE uses QIO (no-wait), with MRKT, in order to provide positive timeout action. In the event the qio times-out (user hit no-scroll for example, or hung up), the QIO is killed. No other error reporting is done, to prevent an in- finite error loop! CALL CALL TYPE,r5,buf,flag INPUT r0 -> GCCI return buffer (reqd if cli command term is output) on r5 parameter list - buf -> ASCIZ buffer to output flag = 0 --> use cli command term = 1 --> output to TI: OUTPUT message sent, errors ignored (!) if flag = 0, LUN 1 set to comand input terminal REGS preserved Program TSTTYPE exercises this module. CHAPTER 7 Test Programs This chapter contains brief descriptions of the test pro- grams used to validate the various modules. 7.1 TSTCRYPT This program validates the CRYPT module. It accepts a line of input from the terminal, encrypts it, then decrypts it. The input and decrypted text are printed on the termi- nal, along with the result of a check that the encrypted text does NOT match the input. Note that TSTCRYPT does not validate the encryption algorithm for security - only that it will decrypt a duplicate of the original plain text. 7.2 TSTLOG TSTLOG exercises the logging facility. It basically calls LOG once per message type. Several 'internal error' messages are logged, in order to exercise the variable par- ameter features. Output from tstlog will be on the console log and error log. This is a useful program for producing sample log reports as well. 7.3 TSTLOOKUP This program validates LOOKUP, and indirectly CRYPT and KEYGEN. It accepts a string from the operator, passes it to lookup, and prints the returned index value. CTRL-Z termi- nates. The returned value is zero if no record found, or the byte offset into a table of responses. It is just pos- sible, especially if the STARTUP.CMD file is faulty, or fol- lowing maintenance shutdowns, that a user may be logged on to the terminal at the time SCLI takes control. This is the only time that this situation can arrise. In the event this happens, the user must satisfy SCLI, in order to return to MCR. Test Programs Page 7-2 7.4 TSTTYPE This program validates TYPE. It dummies up a GCCI buffer with device info (HARDWIRED to tt23:!), then calls TYPE twice. First, a message to the 'command tt' (tt23:), next a call to the 'task ti:'. We don't try to exhaustively exercise the various error conditions, since most are fatal anyway. You can check the timeout by hitting S on tt23: before running the program. 7.5 TSTSLEN This program validates SLEN. It accepts a line of input from TI:, and prints its length as returned by SLEN. CHAPTER 8 Terminal Driver Modifications This chapter discusses the modifications to the RSX terminal driver required to support the security system (SCLI) for remote dial-up lines. 8.1 Overview The RSX-11 (M and M+) terminal driver unconditionally forces MCR to a terminal being answered on a remote line. While intended to provide a consistent interface to remote terminals, this functionality breaks the security system, which depends upon SCLI owning any protected terminals. Equally unfortunate is the fact that TTDRV does not use the normal SCLI$ mechanism to establish MCR, but instead simply hammers the executive data structures directly. The exec is thus unaware that a port's CLI has changed, and does not in- form SCLI of the action. This prevents SCLI from re-taking the port. Fortunately, a very simple patch to the terminal driver will 'correct' this situation. The remainder of this chapter describes the modification, and includes instruc- tions for making the patch either in the sources or via ZAP to an existing system. 8.2 Modification Details The relevant code is in subroutine MANS (modem answer), in module TTMOD.MAC. This file can be found on the distri- bution kits in [11,10]. MANS is called when a remote line is answered (e.g., carrier detected). Its purpose is to place the terminal in a known (and benign) state. MANS mod- ifies the terminal characteristics words, sets the buffer to 72., and forces the CLI to MCR. It then initiates autobaud (if the terminal is set ABAUD), and returns. The switch to MCR is accomplished by one of two in- structions, depending upon certain SYSGEN conditionals. For MPLUS, this is a BIC instruction, while for M it is a MOV instruction. Both are commented as "SET MCR AS CLI". Terminal Driver Modifications Page 8-2 Comment out these instructions. The driver also resets the lower-case bit, enabling lower-to-upper case conversion. Since SCLI is case- sensitive, we wish the terminal to be left in lowercase mode. This is accomplished by locating the BIC instruction containing "U2.LWC" in the first operand. Remove the refer- ence to "U2.LWC", leaving the other bits intact. NOTE Several other characteristics are set in this code section. Most may be eliminated, if it is de- sired. Examples include U2.CRT, U2.ESC, and S3.8BC. It is also possible to alter the default buffer size. The buffer size must be at least 72. for SCLI to operate properly. 8.3 Source Modification The desired method of modifying the driver is at the source level. UIC [1,101] contains the MPLUS files; [1,102] those for M. These uics contains the modified TTMOD.MAC, an unmodified TTMOD.VGN, and TTMOD.COR. Although M and M+ share the same source module, the up- date versions are different, requiring patch sets in both [1,101] and [1,102]. The patches may have to be manually applied, and new correction files built, for later updates or releases. Both patch sets contain the audit trail "JMB227". The simplest way to apply these patches is to copy the modified TTMOD to [11,10] of the sysgen work disk prior to SYSGEN. Since TTDRV is always re-assembled and built by SYSGEN, this will incorporate the patches. It is also pos- sible to manually assemble TTMOD, and rebuild TTDRV post- SYSGEN. Follow the instructions in the release notes for rebuilding a driver. The database doesn't change, so it is possible to use VMR to UNLoad and LOAd the patched driver without creating a new system image. The secure source accounts contain TTMODASM.CMD, which will reassemble TTMOD. This file assumes that TTMOD.MAC ex- ists in [11,10] on the sysgen work disk, which is also the current SY:. Replace module TTMOD in [1,24]TTDRV.OLB, then rebuild. To rebuild TTDRV, use [200,200]TTDRVBLD.CMD. Terminal Driver Modifications Page 8-3 8.4 Patching TTDRV.TSK It is also possible to apply these patches to TTDRV.TSK using ZAP, or to a running system using OPEN. In order to do this, TTDRV.MAP, plus an assembly listing of TTMOD are required. The patches add no code, and are thus simple to make. Simply comment out the "SET MCR" instruction (all three words!), and alter the bitmask for the BIC instruc- tion. The unmodified bitmask is currently 3047, and the patched value 3046. CONTENTS 1. Introduction . . . . . . . . . . . . . . . . . . . . 1-1 1.1 Overview . . . . . . . . . . . . . . . . . . . 1-1 2. SCLI Narrative . . . . . . . . . . . . . . . . . . . 2-1 2.1 SCLI Walkthru . . . . . . . . . . . . . . . . . 2-2 2.1.1 Command Input . . . . . . . . . . . . . 2-3 2.1.2 Mumble Processing . . . . . . . . . . . 2-3 2.1.3 Message Processing . . . . . . . . . . . 2-4 2.1.4 Logging . . . . . . . . . . . . . . . . 2-5 3. Standards . . . . . . . . . . . . . . . . . . . . . 3-1 3.1 Coding standards . . . . . . . . . . . . . . . 3-1 3.1.1 Modularity . . . . . . . . . . . . . . . 3-1 3.1.2 Source Format . . . . . . . . . . . . . 3-1 3.1.3 Source Control . . . . . . . . . . . . . 3-1 3.1.4 Test Programs . . . . . . . . . . . . . 3-2 3.1.5 PSECT Usage . . . . . . . . . . . . . . 3-2 3.1.6 Exceptions . . . . . . . . . . . . . . . 3-3 4. Database . . . . . . . . . . . . . . . . . . . . . . 4-1 4.1 Global Data . . . . . . . . . . . . . . . . . . 4-1 4.1.1 Constants . . . . . . . . . . . . . . . 4-1 4.1.2 TT-TABLE . . . . . . . . . . . . . . . . 4-1 4.1.3 Command Table . . . . . . . . . . . . . 4-2 4.1.4 Reply Strings . . . . . . . . . . . . . 4-3 4.1.5 User-id Strings . . . . . . . . . . . . 4-4 4.1.6 Global Variables . . . . . . . . . . . . 4-4 4.2 Internal Errors . . . . . . . . . . . . . . . . 4-4 4.3 Log Messages . . . . . . . . . . . . . . . . . 4-5 4.4 Key Table . . . . . . . . . . . . . . . . . . . 4-5 5. Maintenance Instructions . . . . . . . . . . . . . . 5-1 5.1 Protected Terminals . . . . . . . . . . . . . . 5-1 5.1.1 USRSB . . . . . . . . . . . . . . . . . 5-1 5.1.2 SCLIDAT . . . . . . . . . . . . . . . . 5-2 5.2 Passwords . . . . . . . . . . . . . . . . . . . 5-2 5.3 Command Table . . . . . . . . . . . . . . . . . 5-3 5.4 Summary . . . . . . . . . . . . . . . . . . . . 5-3 5.4.1 Change Terminals . . . . . . . . . . . . 5-3 5.4.2 Change Passwords . . . . . . . . . . . . 5-3 5.4.3 Change Users . . . . . . . . . . . . . . 5-3 5.4.4 Change Messages . . . . . . . . . . . . 5-4 5.5 Build Instructions . . . . . . . . . . . . . . 5-4 5.5.1 SCLI . . . . . . . . . . . . . . . . . . 5-4 5.5.2 Documentation . . . . . . . . . . . . . 5-5 5.5.3 BYE . . . . . . . . . . . . . . . . . . 5-5 5.5.4 TTDRV . . . . . . . . . . . . . . . . . 5-5 5.6 Initialization . . . . . . . . . . . . . . . . 5-6 6. Module Descriptions . . . . . . . . . . . . . . . . 6-1 6.1 Global Data . . . . . . . . . . . . . . . . . . 6-1 6.2 CRYPT . . . . . . . . . . . . . . . . . . . . 6-1 6.3 DOMSG . . . . . . . . . . . . . . . . . . . . . 6-2 6.4 LOG . . . . . . . . . . . . . . . . . . . . . . 6-3 6.4.1 Notes . . . . . . . . . . . . . . . . . 6-3 6.5 LOOKUP . . . . . . . . . . . . . . . . . . . . 6-4 6.6 MUMBLE . . . . . . . . . . . . . . . . . . . . 6-5 6.7 SLEN . . . . . . . . . . . . . . . . . . . . . 6-6 6.8 TYPE . . . . . . . . . . . . . . . . . . . . . 6-7 7. Test Programs . . . . . . . . . . . . . . . . . . . 7-1 7.1 TSTCRYPT . . . . . . . . . . . . . . . . . . . 7-1 7.2 TSTLOG . . . . . . . . . . . . . . . . . . . . 7-1 7.3 TSTLOOKUP . . . . . . . . . . . . . . . . . . . 7-1 7.4 TSTTYPE . . . . . . . . . . . . . . . . . . . . 7-2 7.5 TSTSLEN . . . . . . . . . . . . . . . . . . . . 7-2 8. Terminal Driver Modifications . . . . . . . . . . . 8-1 8.1 Overview . . . . . . . . . . . . . . . . . . . 8-1 8.2 Modification Details . . . . . . . . . . . . . 8-1 8.3 Source Modification . . . . . . . . . . . . . . 8-2 8.4 Patching TTDRV.TSK . . . . . . . . . . . . . . 8-3