Google
 

Trailing-Edge - PDP-10 Archives - BB-L014X-BM_1990 - t20src/acjfun.rno
There are 9 other files named acjfun.rno in the archive. Click here to see a list.
.ap;.date;.pr;.autosubtitle 4
.lm 5;.rm 75;.ps 59,75;.sthl 6,0,0;.fl substitute
.title Enhanced Access Control Facility Functional Specification
.pa
.figure 15
.c;TOPS-20
.s 1
.c;FUNCTIONAL SPECIFICATION
.s 1
.c;for
.s 1
.c;Enhanced Access Control Facility
.s 5
.c;Gregory A. Scott
.c;LSBU Software Engineering
.s 1
.c;Created: 30 Nov 88
.c;Last Revision: $$date
.s 4
COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION 1989.  ALL RIGHTS RESERVED.
.b
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED ONLY IN
ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF THE ABOVE
COPYRIGHT NOTICE.  THIS SOFTWARE OR ANY OTHER COPIES THEREOF MAY NOT BE
PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON.  NO TITLE TO AND
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
.b
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND SHOULD
NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION.
.b
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS SOFTWARE ON
EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.
.pa
.c;TABLE OF CONTENTS
.s 2
.require "acjfun.rnt"
.pa

.hl1Summary of Functional Change

.hl2Changes from 7(130) to 7(131)

The only change in edit 131 is to change the GOATJ (Attach Job) policy to allow
attach of not-logged-in jobs to terminals for the FTPSRT program (FTPSRT is the
program allowing TCP/IP network access to files).

.hl2Changes from 7(105) to 7(130)

The first release of this software was version 7(105).

Changes to ACJDEC.MAC in edits 106 to 130 are documented below.
.ls
.le
Addition of a cache for the log file, which is a write-behind cache used to
buffer log file writes.
.s 1
The log file is now updated every few seconds (or whenever it is about to be
read or renamed).  The addition of the log file cache causes no externally
visible changes to the software but does improve ACJ performance.  The log file
cache sweep interval can be set in the profile generation phase and defaults to
30 seconds.  The cache can be disabled by setting the log file cache sweep
interval to zero.  The command SET LOG-FILE-CACHE-SWEEP-INTERVAL is used to
change this value.
.le
Addition of a cache for the ACCESS.CONTROL files.
.s 1
The ACCESS.CONTROL cache is organized into NCACHE (default 16) non-contiguous
fixed buffers in memory, each of SCACHE (default 16) contiguous pages.  A
"Cache Block" is allocated for each cache entry and contains the address of the
buffer as and the directory for this entry.  When the cache is full the entry
with the oldest reference date is reclaimed for use.  The addition of the
ACCESS.CONTROL cache causes no externally visible changes to the software but
does improve ACJ performance significantly.  The cache hit/access ratio is now
output in the log file header line as a percentage.
.le
Summary information is now written to the log file when it is closed.
.le
The ACCESS.CONTROL files are now properly read if they contain line numbers (as
generated by a text editor such as EDIT).
.le
The ACJLOG tool is now included which can filter and summarize the access
control log files (see ACJLOG.HLP for more information).
.le
If the access control log filespec is found to have a "*" in it the current
date and time are substituted in the form "yyyy-mm-dd-hh-mm-ss".
.le
Two new GETOK functions were added: GET-DIRECTORY (GTDIR% JSYS) and SET-TIME
(STAD% JSYS).  These are documented in the main text.
.le
A bug in the CREATE-DIRECTORY policy was fixed which caused all directory
deletions (using KILL subcommand of BUILD command) to fail.  This was due to a
RCDIR% JSYS in the CREATE-DIRECTORY policy routine.  The RCDIR% caused the
target directory to be put in the directory cache; the kill would then fail
with the error "Directory file is mapped".  The fix was that if the target
directory was being killed, do a RCDIR% JSYS on another directory, causing the
target directory to be removed from the cache.
.els;

.hl2Problem Discussion and History

The current ACJ we use here has been hacked over from the original ACJ.MEM
file shipped with the GETOK/RCVOK/GIVOK interface was created.  It is hard to
maintain and contains no discernable coherent layout or style.

The ACJ.MEM file distributed to customers is outdated in that it doesn't have a
full implementation of all of the currently supported GETOK functions and also
is in poor style.

The TOPS-20 Security Project is significantly enhancing the amount and type of
data returned by the GETOK interface and major changes will be needed in the
user written ACJ code to take advantage of these new items.

.hl2Description and Goals

Rather than continuing to modify the locally grown ACJ program, the ACJ program
will be broken down into two logical parts: the main ACJDEC.MAC module and the
subroutine module ACJUSR.MAC.  A module ACJSYM.MAC will contain common symbols.

The ACJUSR.MAC files will implement the policy, and the ACJDEC.MAC will contain
all GETOK/GIVOK code as well as general subroutines (such as used for logging
or getting information).  The policy enforced by the current ACJ will be used
as a basis for the new ACJ.  For internal use the old or the new ACJ can be run
as the system ACJ.

The new ACJ program will be written to adhere to TOPS-20 Coding Standards and
with the goals of easy debugging, maintenance, and supportability.  It is also
a goal of this project to distribute this ACJ to the customer base.

The user will execute ACJDEC.MAC, ACJUSR.MAC which will start a "ACJ Profile"
phase in which commands are accepted from the terminal.  These commands control
the policy implemented by the ACJ.

The ACJ.EXE resulting from the generation phase will not have the capability to
change its policy operation.  The ACJ.EXE file will not contain symbols or the
command interface, unless overridden by a compile time switch.
.hl2Limitations and Restrictions

Is it not a goal of this project to enhance performance or reliability over the
previously distributed ACJ.MEM file.

Running this ACJ program will not protect the system against security problems,
but it will enhance the security of the system.

.hl2Supporting Information

For more information on the new GETOK functions to be implemented as part of
the TOPS-20 Security Enhancements Project, see the Functional Specification for
Security Enhancements.

.hl2Security Consciousness

Security is something that must be maintained on many levels in a computer
system environment.  It is important that each site take reasonable care in
protecting the security of the system.  The computer hardware must be
physically secure as well as insuring that the computer software is secure.

It must be remembered that running an ACJ does not make the system secure.  A
properly configured and running ACJ is only a portion of what must be done.  

It is important to take security measures before the system is violated.  It is
suggested that the following also be done in order to provide a secure
atmosphere:

.ls
.le;Usernames: No username should be used by more that one person at a time.
It is important that each person accessing the system should do so with a
username uniquely assigned to that person.  Sharing usernames hampers or in
some cases prevents auditing of security problems.
.le;Passwords: The TOPS-20 monitor provides a number of features that 
help in password management.  It is suggested that the minimum password length
be set to eight characters.  The longer the password is, the harder it is to
guess.  It is suggested that password expiration should be set to 30 days.
Passwords that are changed often are more secure than having the same password
for an extended period of time.  The password dictionary should be enabled.
This new feature will prevent the setting of a password that is in a common
dictionary file, which will make the password harder to guess.
.le;Capabilities: Since a user with WHEEL or OPERATOR capability has the power 
to change many aspects of system operation, the WHEEL and OPERATOR capabilities
should be set on the minimum number of usernames on the system.  A need to
access files should be handled by the existing directory and user groups
structure and not by handing out OPERATOR capability.  Please note that it is a
particularly BAD idea to have one username with WHEEL or OPERATOR that a number
of persons use.
.le;Backups: A "system tape" (containing the monitor, exec, user information,
and system files from the bootable file structure) should be created once a
week.  Not only is this useful in the case of hardware failures, but can be
used to get a known secure copy of the monitor and all other software running
on the system with enabled capabilities.
.le;FILES-ONLY directories:  Directories on the system's PS:#structure that
are not normally user for usernames should be set FILES-ONLY.  This prevents
"accidental" usernames from being created which are obvious security problems.
.le;OPERATOR username: It is suggested that the OPERATOR username be prevented
from logging in interactively by removing its password (or expiring its
password).  OPERATOR should be used to run jobs needed for system operator
(e.g. jobs under SYSJOB and/or PTYCON that are logged in when the system is
reloaded).  A password does not have to be set on OPERATOR in order for jobs to
login to OPERATOR under SYSJOB or PTYCON.  The system operator should use
his/her own username to run the system backups and to run OPR.  If it is
desired that OPERATOR run DUMPER to save the system, this can be done under
PTYCON.
.le;ACJ Policy: The ACJ program provides a critical security function.
The program should be tailored at the site to provide the access control and
logging that the site requires.  This ACJ implements an access policy that lets
users with WHEEL capability do more than users with OPERATOR capability (see
the Login, Attach Job, and Create Directory policy descriptions for more
information).
.le;Secure Files: This ACJ along with the TOPS-20 monitor with the
security project edits allows user selectable control and logging of file
access.  It is suggested that files that are sensitive to the operation and
health of the system be set SECURE and activity should be monitored by looking
at the ACJ log files.  These files would certainly include MONITR.EXE and
EXEC.EXE.  The ACCESS.CONTROL files should also be set secure.  Secure files
and ACCESS.CONTROL are discussed elsewhere in this document.
.le;ACJ Logs: The log files produced by the site's ACJ should be reviewed
daily for possible unusual activity.  Careful monitoring will result in greater
system security since repeat penetrations are the cause of the most severe
security problems.
.le;Local Changes: It is important not to underestimate the positive effect
that a few minor site specific changes have on security.  Anything that makes
the site's system just a little different will slow down an attempted breakin.
For example, it is suggested that the site use the commands available in this
ACJ to change the ACJ log filename from the default.
.els

Maintaining system security on a TOPS-20 7.0 system isn't very difficult.  It
is just a matter of using the provided tools and using common sense.
.hl1Terminology

It is assumed that the reader has a basic knowledge of terms relating to
TOPS-20 monitor calls, but this is not a requirement.

.ls
.le
ACJ - Access Control Job (Access Control Facility).  TOPS-20 allows a site
supplied program to implement policy decisions relating to system resources.
The ACJ is a program that implements policy and control over system functions
on as per site basis.  Each site should have an ACJ to implement policy based
on the needs of that site.
.le
CTERM - A protocol used to simulate remote terminal sessions communicated over
DECnet.
.le
GETOK - Action performed (usually by the monitor through the GTOKM macro) to
ask the ACJ for permission to perform a certain function or obtain ownership of
a certain object.
.le
NRT - A protocol used to simulate remote terminal sessions communicated over
DECnet.  An older protocol that has been superseded by CTERM.
.le
TCP/IP - Transmission Control Protocol / Internet Protocol.  The network
protocol used by many different computer systems manufacturers.
.le
TELNET - A protocol used to simulate remote terminal sessions over TCP/IP.
.els

.hl1Architectural Position

The ACJ program is consulted by the monitor on certain events in order that
local policy can be implemented.  This spec describes a program that is one
implementation of the ACJ.  
.tp 16
.lt

                                +---------+
         ACJPROFILE             | ACJDEC  |
            command ----------->| profile |
              file  <-----------| program |
                                +---------+
                                     |
                                     V
        +---------+             +---------+
        | TOPS-20 |---RCVOK%--->|   ACJ   |
        | monitor |             |  policy |
        |  code   |<---GIVOK%---| program |----> log file
        +---------+             +---------+
                
.el
.hl2Access Control Profile Generation

When the Access Control Facility profile generation program (ACJDEC.EXE) is
run, it will parse commands from the terminal to set the profile for each
possible GETOK function and for each "special" user.  After this process is
complete, a command will be used to write the current settings into a command
file that can be processed for future profile setting sessions.

When the system manager is satisfied with the Access Control Profile and has
written the command file, the policy program is written.  This EXE file
implements the Access Control policy.

.hl2Access Control Facility Operation

The Access Control Facility policy program (ACJ.EXE) is run as a user program.
It interfaces to the TOPS-20 monitor using the RCVOK% and GIVOK% monitor calls.

When the monitor wishes to have the ACJ bless some operation, it puts a request
into the GETOK Queue.  The GETOK Queue is read by the RCVOK% JSYS.  If the
entry is not removed from the GETOK Queue in a reasonable amount of time, a
RCVTMR BUGCHK is issued and the monitor ignores the running Access Control
Facility.

After the ACJ reads the request with RCVOK%, it may log the request and will
decide to allow or deny it.  This information is communicated to the monitor by
using the GIVOK% JSYS.

For each request read by RCVOK%, a GIVOK% JSYS must be executed.  If the
GIVOK% is not executed in a reasonable amount of time, the monitor issues a
GIVTMR BUGCHK and allows or denies the function (based on the function's
default action).

.hl2Program Organization

The three source files that create the profile generation program are called
ACJSYM.MAC, ACJUSR.MAC, and ACJDEC.MAC.  ACJSYM contains all macro and symbol
definitions.  ACJDEC contains the profile generation code, the main
RCVOK%/GIVOK% processing loop, and common subroutines.  The ACJUSR module
contains tables for GETOK function definitions (used in profile and policy
phases), and logging routines and policy routines for each function.
.hl1Related Documents and Standards

Documents that relate to this functional specification are as follows.

.ls "o"
.le;TOPS-20 Functional Specification of Security Enhancements, M. Raspuzzi, 
November 1988
.le;TOPS-20 Monitor Calls Reference Manual, Jun 88, (AA-FV52B-TM)
.le;TOPS-20 Coding Standards, D_. Murphy, March 1983
.le;Final Report on Proposed TOPS-20 Security Enhancements, 
David Velten, 5 Oct 1982, DEC TR-188
.els
.hl1Services Provided

.hl2Access Control Profile

When the profile generation program (ACJDEC) is run, it will prompt for
commands.  A brief description of each of the commands follows.

.hl3 Disable Command

The DISABLE command is used to disable the policy program from receiving
GETOK requests for a particular GETOK function.  The DISABLE command is
followed by a keyword describing the GETOK function.  These keywords are
also used for the ENABLE command.  The keywords and their corresponding
GETOK functions are:

.ls "o"
.le;ACCESS (.GOACC)
.le;ARPANET-ACCESS (.GOANA)
.le;ASSIGN-DEVICE (.GOASD)
.le;ASSIGN-DUE-TO-OPENF (.GOOAD)
.le;ATTACH-JOB (.GOATJ)
.le;CAPABILITIES (.GOCAP)
.le;CLASS-ASSIGNMENT (.GOCLS)
.le;CLASS-SET-AT-LOGIN (.GOCL0)
.le;CREATE-DIRECTORY (.GOCRD)
.le;CREATE-FORK (.GOCFK)
.le;CREATE-JOB (.GOCJB)
.le;CREATE-LOGICAL-NAME (.GOCRL)
.le;CTERM (.GOCTM)
.le;DECNET-ACCESS (.GODNA)
.le;DETACH (.GODTC)
.le;ENQ-QUOTA (.GOENQ)
.le;GET-DIRECTORY (.GOGTD)
.le;GETAB (.GOGTB)
.le;HSYS (.GOHSY)
.le;INFO (.GOINF)
.le;LATOP (.GOLAT)
.le;LOGIN (.GOLOG)
.le;LOGOUT (.GOLGO)
.le;MDDT (.GOMDD)
.le;MTA-ACCESS (.GOMTA)
.le;SECURE-CHFDB (.GOCFD)
.le;SECURE-DELF (.GODLF)
.le;SECURE-OPENF (.GOOPN)
.le;SECURE-RNAMF (.GORNF)
.le;SET-TIME (.GOSTD)
.le;SMON (.GOSMN)
.le;STRUCTURE-MOUNT (.GOSMT)
.le;SYSGT (.GOSGT)
.le;TERMINAL-SPEED (.GOTBR)
.le;TLINK (.GOTLK)
.le;TTMSG (.GOTTM)
.le;USER-TEST (function code 400000)
.els

The keyword ALL can be specified to indicate all functions.

.hl3 Enable Command

The ENABLE command is used to enable the policy program's receipt of
GETOK functions.  The ENABLE command is followed by a keyword describing
which GETOK function to enable (see previous section for listing of
these functions).  After the function, the following keywords can be specified:

.ls "o"
.le;[NO] CONSOLE
.b
The CONSOLE keyword enables display of the logging string to the console 
terminal.   NO CONSOLE is the default.
.le;[NO] DENY-BATCH
.b
The DENY-BATCH keyword causes a request for this function from any batch job
to always be denied.  The default is NO DENY-BATCH.
.le;[NO] DENY-CTY
.b
The DENY-CTY keyword causes a request by a job logged into the system's console
terminal (the CTY) to always be denied.  The default is NO DENY-CTY.
.le;[NO] DENY-DECNET
.b
The DENY-DECNET keyword causes a request by a job which is attached to the
system through DECnet (NRT or CTERM protocol) to always be denied.  The
default is NO DENY-DECNET.
.le;[NO] DENY-DETACHED
.b
The DENY-DETACHED keyword causes a request by a detached job to always be
denied.  The default is NO DENY-DETACHED.
.le;[NO] DENY-LAT
.b
The DENY-LAT keyword causes a request by a job attached to the system through a
LAT terminal to always be denied.  The default is NO DENY-LAT.
.le;[NO] DENY-LOCAL
.b
The DENY-LOCAL keyword causes a request by a job logged into any terminal local
to the system to always be denied.  The default is NO DENY-LOCAL.
.le;[NO] DENY-PTY
.b
The DENY-PTY keyword causes a request by a job attached to a PTY that is not a
batch job to always be denied.  The default is NO DENY-PTY.
.le;[NO] DENY-TCP
.b
The DENY-TCP keyword causes a request by a job attached to the system through
TCP/IP (TELNET protocol) to always be denied.  The default is NO DENY-TCP.
.le;[NO] LOG
.b
The LOG keyword causes a line describing the function to be written to the ACJ
log file.  The logging function is completely independent of policy
enforcement.  The default is LOG.
.le;[NO] POLICY
.b
The POLICY keyword causes enforcement of policy on this function.  If the
function is set NO POLICY, access is denied or allowed based on the monitor's
default action for this GETOK function.  POLICY is enabled by default.
.els

.hl3 Help Command

The HELP command displays a help message in the following format:
.lt

ACJ 7(22) commands:

  DISABLE (function) ALL|name
  ENABLE (function) ALL|name [profile]
  HELP (message)
  SAVE (program in) ACJ.EXE
  SET (mode) keywords
  SHOW ALL|FUNCTION [f]|SETTING [s]|USER [u]
  TAKE (commands from) acjprofile.cmd.0
  USER name [profile]
  WRITE (commands to) acjprofile.cmd.-1

.el

.hl3 Save Command

The SAVE command is used to save a EXE file which is the policy program
implementation.  The default filename is ACJ.EXE.

.hl3 Set Command

The SET command is used to change policy program settings.  The SET command is
followed by one of the following:

.ls "o"
.le;ACCESS-LOG-FILE filespec
.b  
Set the log filespec.  The default filespec is SYSTEM:LOGFILE.LOG.
.le;LOG-FILE-CACHE-SWEEP-INTERVAL n
.b
Sets the log file cache sweep interval.  The log file is updated every few
seconds (or whenever it is about to be read or renamed).  The log file cache
sweep interval defaults to 30 seconds.  The cache can be disabled by setting
the log file cache sweep interval to zero; this will force the log file to be
updated each time a line is written to it.
.le;PRIME-TIME-BEGIN time
.b
Sets the time at which prime time begins on each weekday.  This time is used
when the user profile is set ENABLE-PRIME-TIME for the CAPABILITIES (.GOCAP)
function.  If the desired action is to let anyone enable at any time, the
CAPABILITIES function should be enabled with NO POLICY or disabled.  The
default prime time begin is 07:00 (7 AM).
.le;PRIME-TIME-END time
.b
Sets the time at which prime time ends on each weekday.  This time is used when
the user profile is set ENABLE-PRIME-TIME for the CAPABILITIES (.GOCAP)
function.  If the desired action is to let anyone enable at any time, the
CAPABILITIES function should be enabled with NO POLICY or disabled.  The
default for prime time end is 18:00 (6 PM).
.le;SPY-CHECK-INTERVAL seconds
.b
Sets the time between TLINK%s to jobs that are being spyed on.  Longer times
lower overhead but increase the risk that spying data will be lost.  Shorter
times increase overhead but lower the risk that spying data will be lost.  The
default is 10 seconds.
.le;SPY-LOG-DIRECTORY string
.b
Sets the initial part of the filespec used to write spy logs into.  The string
specified will have "-nodename.username" appended to it in order to create the
log filespec.  The default is SYSTEM:ACJ-SPY, so spy log files would be of the
form "SYSTEM:ACJ-SPY-nodename.username".  These files are always made SECURE by
the ACJ.
.els

.hl3 Show Command

The SHOW command is used to display the various items changed with the
ENABLE, DISABLE, SET, and USER commands.  The SET command is followed by
any of the following.

.ls "o"
.le;ALL
.b;Shows all information possible.
.le;FUNCTION ALL|keyword
.b;Shows profile of all functions or a particular function.
.le;SETTINGS ALL|keyword
.b;Shows all items or a particular item changed by the SET command.
.le;USER ALL|userspec
.b;Shows all user profiles or a particular user profile.
.els

.hl3 Take Command

The TAKE command is used to process a file with commands in it.  It takes one
argument, which is the filename, which defaults to ACJPROFILE.CMD.

.hl3 User Command

The USER command is used to set a user profile entry.  The first argument to
the USER command is the wild user specification that this profile is going to
apply to (e.g. "OPERATOR", "STAFF.*").  A user specification of "*" is allowed,
and will be used for all users not otherwise found in the table.

The wild user specification is followed by keywords that set the user profile.
The keywords are:

.ls "o"
.le;CLASS-AT-LOGIN n
.b;Sets scheduler class "n" at login (.GOCL0 function).
All jobs are created in scheduler class 0.  The _.GOCL0 function is only
invoked by the monitor if if the class scheduler is enabled with class
assignment by policy program.  The default is CLASS-AT-LOGIN 0.
.le;[NO] ENABLE-NON-PRIME-TIME
.b;Can enable capabilities at times other than 7 AM to 6 PM weekdays
(.GOCAP function).  If the desired action is to let anyone enable at any time,
the CAPABILITIES function should be enabled with NO POLICY or disabled.  The
default is NO ENABLE-NON-PRIME-TIME.
.le;[NO] LOGIN-BATCH
.b
The LOGIN-BATCH keyword lets batch jobs login.  The default is NO LOGIN-BATCH.
Note that the LOGIN-PTY keyword is used to control non-batch PTY logins.
.le;[NO] LOGIN-CTY
.b
The LOGIN-CTY keyword lets a job login to the system through the system's
console terminal (the CTY).  The default is LOGIN-CTY.
.le;[NO] LOGIN-DECNET
.b
The LOGIN-DECNET keyword lets a job login to the system through DECnet using
NRT or CTERM protocol.  This keyword should not be confused with remote DECnet
access using the RMSFAL (which is controlled by the LOGIN-DETACHED keyword).
The default is LOGIN-DECNET.
.le;[NO] LOGIN-DETACHED
.b
The LOGIN-DETACHED keyword lets a job login detached.  Digital supplied
software that does detached logins is limited to DIU (Data Interchange Utility)
and RMSFAL (RMS File Access Listener).  If DECnet access is desired using DIU
or RMSFAL then the user profile must be set LOGIN-DETACHED.  The LOGIN-DECNET
keyword is used to to control interactive LOGIN over DECnet.  The default is
LOGIN-DETACHED.
.le;[NO] LOGIN-LAT
.b
The LOGIN-LAT keyword lets a job login to the system through a LAT terminal.
The default is LOGIN-LAT.
.le;[NO] LOGIN-LOCAL
.b
The LOGIN-LOCAL keyword lets a job login to terminal lines connected to the
DECSYSTEM-20 (RSX20F console front end) that are not configured as "REMOTE".
LOCAL lines are normally connected directly to terminals rather than to
communications equipment such as modems or port selecters.  The default is
LOGIN-LOCAL.
.le;[NO] LOGIN-PTY
.b
The LOGIN-PTY keyword lets a job login to a PTY that is not a batch job to
succeed (the LOGIN-BATCH keyword is used to control batch logins).  The default
is LOGIN-PTY.
.le;[NO] LOGIN-REMOTE
.b
The LOGIN-REMOTE keyword lets a job login to terminal lines connected to the
DECSYSTEM-20 (RSX20F console front end) that are configured as "REMOTE".
REMOTE lines are normally connected to modems or port selecting equipment and
not directly to terminals.  The default is LOGIN-REMOTE.
.le;[NO] LOGIN-TCP
.b
The LOGIN-TCP keyword lets a job login to the system through a TCP/IP terminal
(TELNET protocol).  The default is LOGIN-TCP.
.le;[NO] SPY-ON
.b;Will be spyed on when logging in or attaching 
(.GOLOG and _.GOATJ functions).  The default is NO SPY-ON.
.els

The keywords used to control LOGINs are normally used in combination.  For
example if a user should only be able to LOGIN from batch and for DECnet access
using RMSFAL, the user should be set NO LOGIN-CTY NO LOGIN-DECNET NO LOGIN-LAT
NO LOGIN-LOCAL NO LOGIN-PTY NO LOGIN-REMOTE NO LOGIN-TCP (only LOGIN-BATCH and
LOGIN-DETACHED would be allowed).

.hl3 Write Command

The WRITE command is used to extract all current profile information and write
it to a command file.  The WRITE command takes one argument, which is the
filename, which defaults to ACJPROFILE.CMD.

.hl2Access Control Policy

For each GETOK function a policy and logging is implemented by the ACJUSR
module.  All monitor supplied additional information for each GETOK function is
logged (if the function is set LOG or CONSOLE).

The implemented policy is explained for each GETOK function below.  If the
implemented policy is not desired, the function can be enabled with NO POLICY,
or the customer may choose to edit ACJUSR.MAC and implement a local policy.

.hl3 Access (.GOACC)

The ACCES% monitor call is used to implement the EXEC's ACCESS, CONNECT, and
END-ACCESS commands.  The monitor calls the ACJ only if the user is not WHEEL
or OPERATOR, the user does not have directory/user group access, and the user
gave bad password.  Therefore this request is normally almost always denied.

The policy implemented is to allow a directory's owner to always connect to
his/her "owned" subdirectories.  The subdirectories are defined as all
"<username*>" directories on any file structure that is DOMESTIC.  To log all
failed ACCESS or CONNECT commands but prevent users from connecting to their
owned subdirectories without a password or directory/user group access, enable
this function with NO POLICY.

.hl3 Arpanet Access (.GOANA)

The monitor calls the ACJ with this function code for each TCP/IP OPENF% (each
time a user attempts to initiate an outgoing Arpanet connection).

The implemented policy allows access for users with SC%ANA capability only.  To
log all Arpanet access and allow all users Arpanet access, enable this function
with NO POLICY.

.hl3 Assign Device (.GOASD)

The ASND% JSYS is used to implement the EXEC's ASSIGN command.  The monitor
invokes the ACJ with this function code for each ASND% JSYS.

The implemented policy is to only allow users with enabled WHEEL or OPERATOR to
assign MTA devices.  This is to prevent non-enabled users from assigning tape
drives that are set UNAVAILABLE (by OPR command).  All other devices are
allowed.

.hl3 Assign Due To OPENF% (.GOOAD)

The OPENF% monitor call is used to open a device for use.  The monitor calls
ACJ for each assignment of a device due to an OPENF%.  This function is very
similar to the Assign Device (.GOASD) function.  The difference is that the
assign of a device happens because the user has opened the device with OPENF%
rather than assigning the device with ASND%.  For example if a user tries to
open TTY1: without assigning it to his job first (ASSIGN TTY1:), the monitor
assigns the device to the user before letting the OPENF% proceed.  The only
device that is not assigned in this manner are file structures (disks).

The implemented policy is the same as the Assign Device function; to only allow
users with enabled WHEEL or OPERATOR to assign MTA devices.  As with the assign
device function, this is to prevent non-enabled users from assigning tape
drives that are set UNAVAILABLE (by using the OPR command).  All other devices
are allowed.

To log all assignments of devices and enable MTA devices to be assigned enable
this function and the Assign Device function with NO POLICY.

.hl3 Attach Job (.GOATJ)

The ATACH% JSYS is used to implement the EXEC's ATTACH command.  The monitor
calls the ACJ on each ATACH% monitor call.

The attach is denied if:
.ls "*"
.le;The job is a batch job (batch cannot attach to anything).
.le;The target job's user profile says that target user cannot LOGIN 
to the source's line type.
.le;WHEEL-only LOGINs are set for the source line type and the target job
is not WHEEL user.
.le;The target job is batch job and source job is not and enabled WHEEL.
.le;The source job has OPERATOR capabilities enabled and the target 
job is a user with WHEEL (the monitor would usually let the attach happen
without a password).  This prevents a user with OPERATOR capability from
attaching to a job with WHEEL capability in an effort to gain WHEEL capability.
.le;The source job is controlled by a user with OPERATOR capability and 
the target job is a user with WHEEL capability.  This prevents a user with
OPERATOR capability from attaching to a job with WHEEL capability in an effort
to gain WHEEL capability.
.els

.hl3 Capabilities (.GOCAP)

The EPCAP% monitor call is invoked with the EXEC's ENABLE and DISABLE commands.
The monitor calls the ACJ for each EPCAP% JSYS.

The policy routine disallows setting of WHEEL or OPERATOR during non-prime time
unless the user profile has been set ENABLE-NON-PRIME-TIME.  If the desired
action is to let anyone enable at any time, the CAPABILITIES function should be
enabled with NO POLICY or disabled.

.hl3 Class Assignment (.GOCLS)

The monitor calls the ACJ for all attempts to set a job's scheduler class using
the SKED% JSYS.  The OPR command "SET JOB x SCHEDULER-CLASS y" is an example of
this.  However, if a user is not WHEEL or OPERATOR and is trying to set another
job's class, the ACJ will not be consulted and the user will get a CAPX1 error.

The policy routine only allows WHEEL or OPERATOR jobs to change a job's
scheduler class (the same check that is currently performed by the monitor).

.hl3 Class Set At Login (.GOCL0)

The monitor calls the ACJ with this function code each time a job logs in only
if the class scheduler is on and class assignments are by the policy program.

The policy implemented is to use a SKED% JSYS to set the job in a particular
class as specified by the user profile CLASS-AT-LOGIN.  As class zero is the
default class, no SKED% JSYS is done if the CLASS-AT-LOGIN in the user profile
is set to zero (or there is no user profile associated with the user logging
in).  If the job cannot be set in the proper class, the log entry is marked as
"unusual".

.hl3 Create Directory (.GOCRD)

The CRDIR% JSYS is used by the EXEC's _^ECREATE and BUILD commands.  The
monitor calls the ACJ on each and every CRDIR% JSYS.

In monitor's previous to the implementation of the TOPS-20 Security Enhancement
project, the monitor does not furnish us the user's CRDIR% arguments; in this
case we attempt to get them from the monitor by using a combination of the
SNOOP% and XPEEK% monitor calls and the PMOVE (physical move) instruction.  The
PMOVE instruction is only implemented in KL10 microcode version 442 and later.
This microcode is required for TOPS-20 version 7.0 and will work with TOPS-20
version 6.1.

It is very important to not allow <ROOT-DIRECTORY> to have a password, user
groups, directory groups, or be non-files-only.  The reason is that if someone
is allowed to ACCESS or CONNECT the <ROOT-DIRECTORY> or LOGIN to ROOT-DIRECTORY
then this person would have owner access to the ROOT-DIRECTORY and any
directory (or username) on that structure could be changed without enabling
WHEEL or OPERATOR.  The implemented policy denies setting of a non-null
password or any user or directory groups on any <ROOT-DIRECTORY>.

In addition, the policy implemented controls access to DOMESTIC file
structures.  The policy routine only lets enabled WHEELs change a directory's
SECURE, FILES-ONLY, WHEEL, OPERATOR, or SEMI-OPERATOR bits if the structure is
DOMESTIC.  Also non-WHEEL users have to make all NEW directories FILES-ONLY, NO
SECURE, and with no capabilities.  The Boot Structure (BS:) and the Public
Structure (PS:) are always DOMESTIC and cannot be made FOREIGN.  Therefore,
users with OPERATOR capability are prevented from making new usernames or
significantly changing existing usernames on DOMESTIC structures.

.hl3 Create Fork (.GOCFK)

Each time a user runs a program, a process (fork) is created.  The CFORK% JSYS
is used to create forks.  The monitor calls the ACJ for each CFORK% that
creates more than FKCNT forks.  FKCNT is a monitor cell that may be patched by
customers, and is defaulted to 5.

The policy routine always allows the CFORK%.

.hl3 Create Job (.GOCJB)

The monitor calls the ACJ for each CRJOB% JSYS.

The policy routine only allows enabled WHEELs or OPERATORs to perform the
CRJOB%.  To log all CRJOB created jobs but let any user use CRJOB, enable this
function with NO POLICY.

.hl3 Create Logical Name (.GOCRL)

The monitor calls the ACJ for each CRLNM% JSYS functions _.CLNS1, _.CLNSA, 
or _.CLNSY and user is not WHEEL or OPERATOR.  

The policy routine only allows enabled WHEELs or OPERATORs to perform the
CRLNM% (the same check that is currently performed by the monitor).

.hl3 CTERM Connection (.GOCTM)

The monitor calls the ACJ from job 0 on each CTERM connection.  The nodename
and/or user name could be checked to allow access to this system.  NOTE: a
hostile user program can send over any source data that it wants to in the
CTERM connect message.

The policy implemented is to always allow the CTERM connection, since it is
only done by job 0 and the data sent in the CTERM connect message is not
"secure".

.hl3 DECnet Access (.GODNA)

The monitor calls the ACJ for each DECnet (DCN:) OPENF%.

This routine allows access for users with SC%DNA capability only.  To log all
DECnet access and allow all users DECnet access, enable this function with NO
POLICY.

.hl3 Detach (.GODTC)

The monitor calls us for each DTACH% JSYS.

The policy routine always allows the DTACH%.

.hl3 ENQ Quota Set (.GOENQ)

The monitor calls the ACJ only if setting ENQ quota (ENQC% function _.ENQCC)
and the user is not WHEEL or OPERATOR.

The policy routine only allows WHEEL or OPERATOR to perform the function (the
same check that is performed by the monitor).

.hl3 Get Directory (.GOGTD)

The GTDIR% JSYS is used to get information about a directory.

The policy implemented is to always allow the GTDIR% to succeed.  This function
is primarily to assure an audit trail whenever some user gets information about
a directory (INFORMATION DIRECTORY command).


.hl3 GETAB% JSYS (.GOGTB)

The GETAB% monitor call is used to extract information from the monitor.
The monitor calls the ACJ for each GETAB% when the previous context is not
monitor (i.e. when the GETAB% is not executed from within the monitor).

Note that enabling this function, particularly with logging, will cause a high
amount of overhead, and may degrade system response, so enabling this function
must be done with caution.

The policy routine always allows the GETAB%.

.hl3 HSYS% JSYS (.GOHSY)

The monitor calls the ACJ for each HSYS% JSYS.

The policy implemented is to only allow users with enabled WHEEL, OPERATOR, or
MAINTENANCE to shutdown the system.

.hl3 INFO% JSYS (.GOINF)

The INFO% monitor call is used to extract information from the monitor about
systems in the CFS cluster as well as perform cluster send alls
(_^ESEND/NODE:).  The monitor calls us for each INFO% JSYS except when it
thinks that the INFO% JSYS is being executed by a GALAXY component.

Note that enabling this function will cause a high amount of overhead, and may
degrade system response, so enabling this function must be done with caution.

The implemented policy is to always allow the INFO%.

.hl3 LATOP% JSYS (.GOLAT)

The monitor calls the ACJ on all _.LARHC (request host connect) functions only.

The implemented policy is to always allow the LATOP% only if WHEEL or OPERATOR
is enabled.  To log all LATOP% _.LARHC functions and allow all users access to
LATOP%'s _.LARHC function, enable this function with NO POLICY.

.hl3 Login (.GOLOG)

The monitor calls the ACJ for each LOGIN% JSYS.  

The LOGIN is denied if
.ls "*"
.le;The user is trying to LOGIN to ROOT-DIRECTORY (directory number 1).
.le;The user is over quota on the PS:<user> directory.
.le;The user profile specifies that the user cannot LOGIN to this line type.
.le;WHEEL-only LOGINs are set and user is not WHEEL.
.le;The LOGIN is on a non-batch PTY, the controlling job has OPERATOR
capability, and is trying to LOGIN to a username with WHEEL capability.
This prevents a user with OPERATOR from gaining access to a job with WHEEL.
.els

In addition to the above policy, if the user is set SPY-ON he will be spyed
upon and the LOGIN entry in the log file will be marked as "unusual".  Users
with SPY-ON enabled are suspected intruders that are attempting to use the
system without authorized access.  If use of a particular username is suspect,
the SPY-ON log files can be used to trace the actions of these these intruders.

.hl3 Logout (.GOLGO)

The monitor calls the ACJ each time a job wants to log itself out.

The request is denied if the user is over quota on the PS:<USER> directory.

.hl3 MDDT% JSYS (.GOMDD)

The monitor calls the ACJ only if user is attempting to enter MDDT and has
WHEEL or OPERATOR capability.

The implemented policy is to disallow entering MDDT by any user who is not a
WHEEL.  To log all MDDT entries functions and allow all OPERATOR and WHEEL
users to enter MDDT, enable this function with NO POLICY.

.hl3 MTA Access (.GOMTA)

The monitor calls the ACJ for labelled MTA access where (1) the label type is
TOPS-20 and access is by non-owner and there is a protection failure; (2)  if
ANSI labels and volume accessibility is not "full"; (3) if EBCDIC labels and
accessibility byte is from 1 to 3 inclusive.

The implemented policy is to always allow the access.  An MTU% JSYS could be
used to check the labels on the tape for user access to labelled tape.

.hl3 Secure CHFDB% (.GOCFD)

The monitor calls the ACJ for each CHFDB% that clears or sets the FB%SEC
(secure) bit for a file.

The implemented policy is to allow the request based on whatever is contained
in the ACCESS.CONTROL file.  

If there is no ACCESS.CONTROL file in the same directory as the secure file,
then setting or clearing of the secure bit is allowed and the request is logged
as unusual.

There are currently three special cases of changing FB%SEC that are always
allowed without logging in order to preserve the current and separate actions
of files that aren't secure.  These special cases allow a full or incremental
restore using DUMPER to work as well as it always has.

.ls
.le
A CHFDB to clear FB%SEC on a totally new file type always works with no
logging.  This allows nosecure files to be created in a directory without some
kind of ACCESS.CONTROL keywords (for example DUMPER restoring nosecure files)
causing lots of unusual logging on files that are not intended to be secure.
.le
CHFDB not really changing SECURE on new file generation always works with no
logging.  This allows new generations of files to be copied even if stupid
programs (such as FCOPY and DUMPER) set the .FBCTL word with FB%SEC the same as
it is now.  A case of this is when DUMPER restores new generations of nosecure
files.
.le
If access is allowed because there is no ACCESS.CONTROL file and the user is
trying to clear FB%SEC, let this happen without logging.  This happens when an
existing nosecure file is overwritten with new contents and the program is
attempting to clear FB%SEC.  A case of this is when DUMPER is restoring
(overwriting) a nosecure MAIL.TXT.1.
.els

.hl3 Secure DELF% (.GODLF)

The monitor calls the ACJ for each DELF% or DELNF% that is deleting a file set
SECURE.

The implemented policy is to allow the request based on whatever is contained
in the ACCESS.CONTROL file.

If delete access is attempted to a file that is set secure and there is no
ACCESS.CONTROL file in the same directory as the secure file, then access is
allowed and the request is logged as unusual.

.hl3 Secure OPENF% (.GOOPN)

The monitor calls the ACJ for each OPENF% that is opening a file set SECURE.

The implemented policy is to allow the request based on whatever is contained
in the ACCESS.CONTROL file.

If read, write, or append access is attempted to a file that is set secure and
there is no ACCESS.CONTROL file in the same directory as the secure file, then
access is allowed and the request is logged as unusual.

.hl3 Secure RNAMF% (.GORNF)

The monitor calls the ACJ for each RNAMF% that is renaming a file set SECURE.
This function may be called twice: once for the "old" filename, and once for
the "new" filename.  

The implemented policy is to allow the request based on whatever is contained
in the ACCESS.CONTROL file.

If rename access is attempted to a file that is set secure and there is no
ACCESS.CONTROL file in the same directory as the secure file, then access is
allowed and the request is logged as unusual.

.hl3 Set Time (.GOSTD)

The STAD% JSYS is used to set the system time.

The policy implemented is to always allow the STAD% to succeed.  This function
is primarily to assure an audit trail whenever the system date and time is
changed.

.hl3 SMON% JSYS (.GOSMN)

The SMON% JSYS is used to set or clear operating system features (such as
account validation, logins allowed, etc.) and is usually invoked with commands
in SYSTEM:7-CONFIG and the EXEC's _^ESET command.  The Monitor calls the ACJ
for each SMON% not done by an enabled WHEEL or OPERATOR.

The policy implemented is to allow SMON% only by enabled WHEEL or OPERATOR (the
same check that the monitor currently makes).

.hl3 Structure Mount (.GOSMT)

The monitor calls the ACJ for each and every MSTR% increment mount count
function (.MSIMC function).  Any job must have a "Regulated" file structure
mounted in order to use it.

The implemented policy is to always allow the increment of the mount count and
let normal file and directory protection handle security.

.hl3 SYSGT% JSYS (.GOSGT)

The SYSGT% monitor call is used to extract information from the monitor.
The monitor calls us for each SYSGT% when the previous context is not monitor.

Note that enabling this function will cause a high amount of overhead, and may
degrade system response, so enabling this function must be done with caution.

The implemented policy is to always allow the SYSGT%.

.hl3 Terminal Speed (.GOTBR)

The monitor calls the ACJ for each attempt to set terminal speed using the
MTOPR% function _.MOSPD.

The policy implemented is to disallow the MTOPR% unless WHEEL or OPERATOR is
enabled.

.hl3 TLINK% JSYS (.GOTLK)

The monitor call used to implement the EXEC's ADVISE, TALK, BREAK, and REFUSE
commands is the TLINK% JSYS.  The monitor calls us the ACJ for each TLINK% JSYS
when previous mode is not monitor mode (the TLINK% is being done inside the
monitor).

The implemented policy is to always allow the TLINK%.  If the user is set
SPY-ON, the log entry will be marked as "unusual".

.hl3 TTMSG% JSYS (.GOTTM)

The monitor call used to implement the _^ESEND and SEND commands is the TTMSG%
JSYS.  The monitor calls the ACJ for each TTMSG% JSYS when the previous mode is
not monitor mode (the TTMSG% is not being done by the monitor).

The implemented policy is to only allow enabled WHEEL or OPERATOR to do the
TTMSG%.

.hl3 USER-TEST (400000)

The GETOK% facility allows user (site specific) functions in the range 400000
to 777777.  In order to provide a example of how these functions could be added
to this ACJ, the USER-TEST function (function 400000) is implemented.  The test
of the function is easily accomplished in DDT.  The source code contains
information and suggestions on implementation of the site specific GETOK%
functions.

.hl2 Sample ACJPROFILE.CMD

The following is a sample ACJPROFILE.CMD file.  This is the file is written
with the WRITE command and read with the TAKE command.

This example shows the type of changes that can be done from the default
settings to provide the site with a access control policy that is tailored to
the site.  The ACJPROFILE.CMD file should be kept SECURE as well as ACJDEC.EXE
and the ACJ source files.
.lt

! ACJ 7(126) profile written by SCOTT at 18-Apr-89 14:30:11
Set ACCESS-LOG-FILE BS:<LOGS>ACCESS-CONTROL.LOG
Set LOG-FILE-CACHE-SWEEP-INTERVAL 30
Set PRIME-TIME-BEGIN 07:30
Set PRIME-TIME-END 18:00
Set SPY-CHECK-INTERVAL 10
Set SPY-LOG-DIRECTORY BS:<LOGS>INTRUDER
Enable ACCESS
Enable ARPANET-ACCESS NO POLICY
Enable ASSIGN-DEVICE NO LOG
Enable ASSIGN-DUE-TO-OPENF NO LOG
Enable ATTACH-JOB
Enable CAPABILITIES DENY-DECNET DENY-TCP
Enable CLASS-ASSIGNMENT DENY-BATCH DENY-PTY
Enable CLASS-SET-AT-LOGIN NO LOG
Enable CREATE-DIRECTORY CONSOLE DENY-BATCH DENY-CTY DENY-PTY
Disable CREATE-FORK
Enable CREATE-JOB NO POLICY
Enable CREATE-LOGICAL-NAME DENY-BATCH DENY-DETACHED DENY-PTY
Enable CTERM
Enable DECNET-ACCESS NO POLICY
Disable DETACH
Disable ENQ-QUOTA
Enable GET-DIRECTORY
Disable GETAB
Enable HSYS DENY-BATCH DENY-DECNET DENY-DETACHED DENY-PTY DENY-TCP
Disable INFO
Disable LATOP
Enable LOGIN
Enable LOGOUT
Enable MDDT DENY-BATCH DENY-DETACHED DENY-PTY
Disable MTA-ACCESS
Enable SECURE-CHFDB
Enable SECURE-DELF
Enable SECURE-OPENF
Enable SECURE-RNAMF
Enable SET-TIME
Enable SMON DENY-BATCH DENY-DETACHED DENY-PTY
Disable STRUCTURE-MOUNT
Disable SYSGT
Enable TERMINAL-SPEED
Disable TLINK
Disable TTMSG
Disable USER-TEST
User * CLASS-AT-LOGIN 1
User BATCH-ADMIN CLASS-AT-LOGIN 1 NO LOGIN-CTY NO LOGIN-DECNET -
	NO LOGIN-DETACHED NO LOGIN-LAT NO LOGIN-LOCAL NO LOGIN-PTY -
	NO LOGIN-REMOTE NO LOGIN-TCP
User CLEMENS CLASS-AT-LOGIN 1 ENABLE-NON-PRIME-TIME
User CONDOR CLASS-AT-LOGIN 1 SPY-ON
User EE.* CLASS-AT-LOGIN 2 NO LOGIN-TCP
User F-S CLASS-AT-LOGIN 1 ENABLE-NON-PRIME-TIME
User GARKTRON CLASS-AT-LOGIN 1 ENABLE-NON-PRIME-TIME
User GAS CLASS-AT-LOGIN 1 ENABLE-NON-PRIME-TIME
User LITTLETON CLASS-AT-LOGIN 1
User OPERATOR ENABLE-NON-PRIME-TIME NO LOGIN-DECNET NO LOGIN-DETACHED -
	NO LOGIN-REMOTE NO LOGIN-TCP
User SPITBROOK CLASS-AT-LOGIN 1 NO LOGIN-TCP SPY-ON
User YAK.* CLASS-AT-LOGIN 2
.el

.hl2Access Control Log Files

The access control log files are an important part of the security provided by
the ACJ.  This log file should be reviewed once a day to look for unusual
activity.  The log file is always made SECURE to prevent unauthorized access.
A new generation of the log file is created each time the ACJ is run and each
night at midnight.

.hl3Log File Format

The log file is split into pages with a header on each page.  The first line of
the header contains the ACJ version, system nodename, current date time, page
number.  The second and third lines summarize the activity so far: number of
requests allowed, denied, and failed; CPU time used; and "uptime" of the ACJ.

The log file has been formatted so that each activity results in one line of
text in the log file.  The first item is the time of day.  The second item is
the username requesting the operator (for the LOGIN function the username that
is trying to LOGIN will be in this field).  The next field is the access
control function.  Following the function, information about the job is output.
This information consists of the job number, controlling job if job being run
on a PTY, "batch" if a batch job, terminal number, network origin string if a
network terminal, and the job's current program name.  Finally, the enabled
capabilities of the process attempting access is output.

Following that fixed information is a comma and information that is specific to
this request type.  For example if a user is enabling capabilities, the desired
capabilities are shown.

At the end of the line one of three strings may appear.
.ls
.le
"[Denied]" indicates that the ACJ denied the request.  For example, a user
tried to login and isn't allowed to login to that terminal type.
.le
"[Failed]" indicates that the ACJ allowed the request but that the action
failed.  For example, a user tried to login and gave a bad password.
.le
"[Unusual]" indicates that the ACJ allowed the request but it is in some way
unusual.  For example, a user login when that user is set SPY-ON.  The
conditions under which the request is considered unusual is documented in the
per-function documentation (section 5.2.*).
.els

.hl3Log File Examples

To illustrate the format of the log file, a few examples will be given.  First
an example of the header:
.nf;.b;.lm+5
ACJ 7(100) on GARK, Thursday, February 2, 1989 00:00:00, page 1
Allowed 782 requests, denied 8 requests, 5 requests failed
Used 1:09.32 in 11:57:56.69
.f;.b;.lm-5
The header shows that this log file was started at midnight and the ACJ has
been up about 12 hours, processing 790 requests.
.tp10;.nf;.b;.lm+5
00:00:47 OPERATOR Open-assign job 194 ctrl 193 TTY233 GALAXY opr ana, device PTY7
00:00:47 OPERATOR Assign job 194 ctrl 193 TTY233 GALAXY opr ana, TTY241
00:00:48 OPERATOR CRJOB job 194 ctrl 193 TTY233 GALAXY opr ana
00:00:48 SCHMITT Login job 206 batch TTY241 EXEC, by OPERATOR job 194 ctrl 193 TTY233 GALAXY
00:00:49 SCHMITT Caps job 206 batch TTY241 ENABLE, desired whl
00:01:36 OPERATOR Logout job 194 ctrl 193 TTY233 GALAXY opr ana, target SCHMITT job 206 batch TTY241 EXEC
.f;.b;.lm-5
These entries show a batch job execution.  OPERATOR running BATCON opened a
PTY, assigned it to itself, created a job, which logged in to user SCHMITT.
That user enabled capabilities then the batch job ran to completion.  The job
running BATCON than logged out the batch job.
.nf;.b;.lm+5
08:35:49 OPERATOR Cterm job 0 Det SYSJOB, from GIDNEY::SGAGNE
08:35:55 SGAGNE Login job 214 TTY364 GIDNEY::SGAGNE(CTM) LOGIN
.f;.b;.lm-5
The next two entries show an incoming CTERM connection from system GIDNEY user
SGAGNE, who proceeds to login to this system.
.nf;.b;.lm+5
09:38:48 not-logged-in Attach job 214 TTY444 LAT1(LAT) ATTACH, target GAS job 207 Det DETACH [Failed]
09:38:58 not-logged-in Attach job 214 TTY444 LAT1(LAT) ATTACH, target GAS job 207 Det DETACH
.f;.b;.lm-5
User GAS attempted to attach to his detached job, and apparently typed an
incorrect password (note "[Failed]").  On the second try he succeeded and
attached to his job.
.nf;.b;.lm+5
09:39:32 OPERATOR DECnet job 198 ctrl 193 TTY237 MX opr ana, to VAXVLN
09:47:11 OPERATOR Secure-OPENF job 198 ctrl 193 TTY237 MX opr ana, read write PUBLIC:<APUCHRIK>MAIL.TXT.1
09:49:15 APUCHRIK Secure-OPENF job 199 TTY435 LAT1(LAT) MS, read write preserve-dates PUBLIC:<APUCHRIK>MAIL.TXT.1
.f;.b;.lm-5
The first entry shows the OPERATOR job running MX connecting to system VAXVLN
using DECnet.  The second entry shows the MX job delivering mail to user
APUCHRIK, who has a secure MAIL.TXT.  The third entry shows this same user
accessing his mail file with MS.
.nf;.b;.lm+5
19:17:56 JWONG Terminal-speed job 216 TTY3 EXEC, TTY3 input 2400 output 2400 [Denied]
19:38:00 OPERATOR Secure-OPENF job 215 ctrl 206 TTY243 DUMPER opr ana, read preserve-dates RANDOM:<RASPUZZI.MAIL>JAN89MAIL.TXT.1 [Denied]
19:38:24 OPERATOR Secure-OPENF job 211 ctrl 206 TTY241 DUMPER opr ana, read preserve-dates WORK:<DEVANS.POOF>BOBBIE.MAIL.1 [Unusual]
.f;.b;.lm-5
The first line shows a user trying to set TTY3's terminal speed.  This request
is denied.  The second and third lines show OPERATOR jobs running DUMPER to
save the system.  The second line shows that user RASPUZZI didn't allow
OPERATOR read access to a file; the access failed and the file is not backed
up.  The third line shows that a SECURE file was opened for reading but there
was no ACCESS.CONTROL file present in that directory.  The request is marked as
unusual and access is allowed.

.hl2Secure Files and ACCESS.CONTROL

The implementation of GETOK functions _.GOOPN, _.GORNF, _.GODLF, and _.GOCFD
allows the ACJ to implement access control of secure files.  When the monitor
calls the ACJ with one of these functions, the policy implementation is as
follows.

.hl3 Secure File Policy Implementation

The monitor furnishes the ACJ with the filename (and in the case of _.GOOPN the
desired access).  The ACJ then tries to open the file ACCESS.CONTROL in the
same directory as the file that is being accessed.  

If the ACCESS.CONTROL file does not exist or cannot be opened, access is
allowed and logged as unusual.

If a match for the file cannot be found in ACCESS.CONTROL, or a syntax error is
detected while reading a line in ACCESS.CONTROL, access is denied.

If the ACCESS.CONTROL file allows access to the secure file, then access is
granted.

In any case the attempted access is logged only if the function (Secure-CHFDB,
Secure-DELF, Secure-OPENF, or Secure-RNAMF) is set to LOG.

.hl3 Format of ACCESS.CONTROL

The format each line of ACCESS.CONTROL is "filename keyword user ... user,
keyword user ... user, ...".  Any combination of spaces and/or tabs is allowed
as field delimiters.  Embedded comments are surrounded by exclamation points,
comment lines are preceded by a semicolon.  A hyphen at the end of the line is
the continuation character.

The filename is the first field on each line.  When the ACJ is searching the
ACCESS.CONTROL file, the first filename field that matches is used.

.tp 8
Following the filename are access keywords followed by a list of usernames.
Each keyword and list of usernames are separated by a comma.  The access
keywords are:
.ls "*"
.le;ALL (all access)
.le;APPEND (OPENF% append access)
.le;DELETE (DELF%/DELNF% deleting the file)
.le;NOSECURE (CHFDB% clearing FB%SEC)
.le;READ (OPENF% read access)
.le;RENAME (RNAMF% to rename the file from or to filename)
.le;SECURE (CHFDB% setting FB%SEC)
.le;WRITE (OPENF% write access)
.els

It is assumed that the file ACCESS.CONTROL itself is set secure.  If this is
not done, the file can be changed too easily.  Even if access is not granted to
the ACJ, it can still read the file as the ACJ can always read any file on the
system (the job running ACJ is not subject to access control).

.hl3 Examples of ACCESS.CONTROL Files

The following example illustrates how user Cloyd has set up his ACCESS.CONTROL
file on his login (PS:) directory.
.lt

!Last edited by Cloyd 20-Dec-88 10:20:33

ACCESS.CONTROL.* ALL Cloyd,-
        READ Operator, SECURE Operator

MAIL.TXT.* ALL Cloyd,-
        READ Operator, SECURE Operator, WRITE Operator

PERSONNEL-REVIEWS.*.* READ Gidney Prospector, ALL Cloyd,-
        READ Operator, SECURE Operator

*.*.* ALL Cloyd
.el

The first line in the file is a comment line.

The second line is for all ACCESS.CONTROL files.  At this site the Operator
username is used to backup files on this system.  Because of this, Operator must
have READ in order to backup the file to tape using the DUMPER program.  It is
very important to include Operator in the list of users that can read all
SECURE files; if this is not included the files could not be backed up by the
nightly Operator job that runs DUMPER.  Operator is also allowed to set this
file secure.  This would happen in case the file structure has been damaged and
is being restored from tape.  Operator must have SECURE access in order to set
this file SECURE after it is restored from tape.  Note that Operator is not
allowed to set the file NOSECURE which could be a security problem.  The owner
is allowed all access.

The third line is for access to Cloyd's mail file, because Cloyd wants to keep
his mail private.  Again Cloyd has full access, and the Operator is allowed to
read it and set it SECURE.  Operator also has to be able to write the mail file
(the job running MX is under the Operator user name).

The next line shows how to use the ACCESS.CONTROL keywords to allow restricted
access to sensitive files.  Users Gidney and Prospector are allowed to read the
personnel reviews written by Cloyd.  (Of course Cloyd has full access and the
usual access for Operator.)  Not that the use of a hyphen between fields in the
file indicates a continuation line is to follow.

The final line of this file is give user Cloyd full access to any other files
that didn't match the above filespecs and that are set SECURE in this
directory.  Without this line, Cloyd would not be able to access any files that
were set SECURE.  

To further help illustrate the techniques involved in using ACCESS.CONTROL
files, an example of an ACCESS.CONTROL file that might be placed in the
<SYSTEM> directory on the boot structure on this system follows.

.lt

!Last edited by STAFF.GREG 10-Dec-88 20:33:10

ACCESS.CONTROL.*  READ Operator Staff.Mike Staff.Greg,-
                  SECURE Operator Staff.Mike Staff.Greg,-
                  WRITE Staff.Mike Staff.Greg,-
                  RENAME Staff.Mike Staff.Greg

ACJ.EXE.*  READ Operator Staff.Greg, SECURE Operator Staff.Greg,-
           WRITE Staff.Greg, NOSECURE Staff.Greg

*.*.*  READ *,-
       WRITE Staff.* Operator,-
       SECURE Staff.* Operator,-
       RENAME Staff.*,-
       ALL Staff.Mike Staff.Greg Staff.Dave
.el

Users Operator, Staff.Mike, and Staff.Greg are allowed to read the
ACCESS.CONTROL file and set it secure.  Users Staff.Greg and Staff.Mike have
WRITE and RENAME access.  If the ALL access is not being used, WRITE and RENAME
access is often used.  If a text editor is used to edit the file, RENAME access
is usually required since the text editor may rename a temporary file to the
new version, or it may rename the old version to a backup file.

The file ACJ.EXE can be read and set secure by Operator; only STAFF.GREG may
write the file or set it NO SECURE.  Therefore the ACJ will disallow any
attempts to delete or rename ACJ.EXE.*

All other secure files in this directory can be read by anyone (given that the
directory and file protections allow this); written by Staff.* and Operator;
renamed by Staff.*; and renamed, deleted and SET [NO] SECURE by Staff.Mike,
Staff.Greg, or Staff.Dave only.
.hl1Services Required

The services required only include (1) the RCVOK% and GIVOK% monitor calls and
(2) the _.SFSOK functions of the SMON% and TMON% monitor calls.

In order to enjoy all features implemented in this program, the running monitor
must include the edits associated with the TOPS-20 Security Enhancement
project.

The ACJ is written to be able to gracefully handle monitors which do not have
the newer GETOK functions included (those that are a part of the TOPS-20
Security Enhancements).  In this manner the ACJ may be run on earlier monitors.
However older monitor testing will only occur on 7.0 autopatch 20 TOPS-20.
Older monitors (7.0 prior to autopatch 20, 6.1, 6.0, 5.1, and 4.1 monitors)
will not be tested but can be expected to work.
.hl1Major Algorithms

The profile generation sets up tables in low memory.  The profile
generation code and all program symbols are placed in the program's high
segment (starting at 400000 octal).  All of the access control code and common
subroutines are kept in low memory.

The profile generation phase is implemented using the standard COMND% JSYS
interface.  When the profile generation phase is complete, the SAVE command is
used to create a runnable ACJ.  Only the low segment is saved, so that no
program symbols or commands to change the profile or policy are saved with the
runnable ACJ.

The access control program contains an initialization section to perform TMON%
and SMON% functions to set the fork up as the system access control facility.

A main loop is then entered, which performs the following steps.
.ls
.le;Storage that needs to be cleared on each request is zeroed.
.le;A RCVOK% is done to read one request from the monitor.  The ACJ blocks
in the RCVOK% until a there is a function to read in the GETOK request queue.
.le;A internal table of enabled functions is searched to find the offset
in the per-function tables.
.le;A internal table of user profiles is then searched to find
any special user profile bits.
.le;A function specific logging routine is called
to create a string to be sent to the log file.
.le;A function specific policy routine and a general policy routine are called
to determine if the function should be allowed or denied.  If the function
should be denied a bit is lit.  If the function should be unusual a bit is lit.
.le;Using this information a GIVOK% is done.
.le;A common routine is called in case the ACJ needs to wait to see 
if the function failed.  If the function failed, a bit is lit.
.le;A common routine is called to append "[Denied]", "[Failed]", or "[Unusual]"
to the logging string and then this string is sent to the terminal or log file
as specified by the function profile bits.
.le;If the log file needs to be closed and reopened, this is done.
.le;Loop for more requests.
.els

Upon a ACJ crash all functions that were enabled are disabled, an ACJ crash
dump is taken, and the program halts (see Error Handling section for more
details).
.hl1Performance Expectations

The new ACJ will be coded in such a way as to provide the best performance
possible.  However, there are no particular performance expectations or goals.
.hl1Error Handling

All monitor calls that fail where failure is significant to the ACJ will be
handled using the JSERRO macro or the OJSERR macro.  The JSERRO macro
dispatches with a ERJMP or ERCAL (depending on its arguments) and OJSERR
dispatches with CALL (PUSHJ P,).  Each error (in either profile or policy
phases) will be printed on the controlling terminal.  Each error when running
as the policy program will also be written to the log file.

Errors caused by the ACJ attempting to use GETOK functions that are not yet
implemented will be gracefully handled (i.e. no error messages will be printed
and the particular function will just not be used).

Errors while writing to the log file will cause the log file to be closed.  A
new log file will then be opened.  If a new log file cannot be opened, a
message will be printed on the console.  Each time there is something to log
and no log file is open, a new log file will be attempted.

Serious errors in the ACJ (e.g. RCVOK% and GIVOK% errors) are handled with the
"BUG" macro.  This macro will cause the ACJ to crash.  The ACJ crash routine
(called BUGHLT) will save all of the ACs and last TOPS-20 error code, disable
all enabled GETOK functions, then write a ACJ crash dump and halt.  The
filename of the dump will be "DMP:ACJ-edit-code-CRASH.EXE", where "edit" is the
ACJ edit number and "code" is the ACJ crash code given in the BUG macro.  This
ACJ crash dump may be examined to determine the cause of the problem.  Since no
symbols will be present, FILDDT must be used to get symbols from a matching
ACJDEC.EXE.
.hl1Diagnostic Features

Diagnostic features will be limited to the ACJ crash dumps and error messages
described in the previous section.
.hl1Documentation Impact

There is no documentation impact from this project.
.hl1Constraints and Tradeoffs

Since this program is not overly complex and its debugging can easily be
accomplished, no design specification will be written.

It is clear that not all customers will be able to use this program without
modification unless each step in the program is controllable in the policy
setting phase.  This would make the program much more complicated and
needlessly complex.  It is hoped that only minor modifications would be needed
at any customer site and that these modifications would only take place in the
ACJUSR module.

There are no significant risks associated with this project.
.hl1Packaging/Building/Installation

The source files will be supplied to the customer base using the Autopatch
process.  A _.CTL file will be furnished which will build the EXE file from the
source _.MAC files.
.pa
.hl1Revision History
.s 2
.lt
Date       Rev  Author       Description
----       ---  ------       -----------
30-Nov-88   1   GScott       Creation
 5-Dec-88   2   GScott       Comments from developers
 7-Dec-88   3   GScott       Add new commands and functions
20-Dec-88   4   GScott       Adding new keywords and fix mistakes
28-Dec-88   5   GScott       Add new operation of GOCFD and GOOPN
 6-Jan-89   6   GScott       Include edits in ACJ 7(55)
12-Jan-89   7   GScott       Add clarification on several GETOK functions
26-Jan-89  10   GScott       Add user function and slight cleanup
 2-Feb-89  11   GScott       Add NOSECURE
 6-Feb-89  12   GScott       Add special CHFDB cases
 4-Apr-89  13   GScott       Add changes from edits 106-124
18-Apr-89  14   GScott       Add changes from edits 125 and 126
25-May-89  15   GScott       Add changes from edits 127 and 130
.el