Trailing-Edge - PDP-10 Archives - BB-L288A-RM - swskit-documentation/getok.mem
There are 5 other files named getok.mem in the archive. Click here to see a list.

! d i g i t a l !   I N T E R O F F I C E  M E M O R A N D U M

TO:  Monitor Attendees List
                                       DATE:  March 27, 1979

                                       FROM:  R. MCLEAN

                                       DEPT:  DEC10 S. E. Dept.

                                       LOC:   MR1-2  EXT:  6113

DISTRIBUTED: May 1, 1978               FILE:  GETOK.MEM

REVIEWED: May 1, 1978                  PDM #: RHM-78-002-01-U


It has been requested by a number of customers, especially  customers
in  the  education  business,  that we add special controls on system
resources.  In general, these people have asked for a  way  to  limit
access  to  assignable  devices such as TTYs, PTYs, MTAs, etc.  Since
each customer has a different idea on  how  the  controls  should  be
administered,  This  implements a mechanism that allows each customer
to  write  a  tailored  utility  that  grants  access  or  privileges
according  to  the requirements of that installation.  This mechanism
would also provide a generalized facility for the customers to expand
the system capabilities to suit their needs.

This proposal requests implementation of three new JSYSs.  The  first
JSYS,  GETOK,  allows  a  user program or process to request approval
before performing a controlled function.  This JSYS  as  an  internal
call will be imbedded in the monitor at critical locations to control
things like device assignments, capability enabling, etc.  The second
JSYS  RCVOK,  is a privileged JSYS that returns the users parameters.
The third JSYS, GIVOK, is a privileged JSYS that allows  the  special
approval  program  written  by  the  customer  to  make all decisions
concerning the controlled resources.
To:  Monitor Attendees List                                    Page 2


Accepts in AC1/ Function Code
           AC2/ Address of Argument Block (if needed)
           AC3/ Length of the Argument Block
           AC4/ Job number for  which  permission  is  requested  (-1
                means this job)


Returns +1:     Request has been OK'd

Causes an illegal instruction trap if the request is denied.

Function Codes:

    1   .GOASD  Assign a device
                Arg 0/  Error block address
                Arg 1/  Device Designator

    2   .GOCAP  Enable Capabilities (right half privileges only)
                Arg 0/  Error block address
                Arg 1/  New Capability Word

    3   .GOCJB  Allow CRJOB JSYS to be executed
                Arg 0/  Error block address

    4   .GOLOG  Allow LOGIN
                Arg 0/  Error block address
                Arg 1/  User Number

    5   .GOCFK  Allow CFORK (only done after Nth fork)
                Arg 0/  Error block address
                Arg 1/  Number of forks already in use by job

    6   .GOTBR  Set Terminal Baud Rate
                Arg 0/  Error block address
                Arg 1/  Line Number 
                Arg 2/  Input speed ,, Output speed

   7    .GOLGO  Allow logout when the directory is over quota
                Arg 0/  Error block address
                Arg 1/  Number of pages used
                Arg 2/  Directory quota (permanent or working?)
                Arg 3/  User requesting logout

   10   .GOENQ  Allow setting of ENQ quota
                Arg 0/  Error block address
                Arg 1/  Desired Quota
                Arg 2/  Job number

   11   .GOCRD  Allow Directory Creation
                Arg 0/  Error block address
To:  Monitor Attendees List                                    Page 3

   12   .GOSMT  Allow Smount of Structure
                Arg 0/  Error block address
                Arg 1/  Device designator

   13   .GOMDD  Allow MDDT Entry
                Arg 0/  Error block address

   14   .GOCLS  Set class of job
                Arg 0/  Error block address
                Arg 1/  Job number
                Arg 2/  New class

   15   .GOCL0  Set class at LOGIN
                Arg 0/  Error block address

   16   .GOMTA  Verify labeled tape access
                Arg 0/  Error block address
                Arg 1/  Access character from HDR1
                Arg 2/  User number
                Arg 3/  MT unit number
                Arg 4/  Access desired (FP%xxx)
                Arg 5/  Label type (.LTxxx)

17      .GOACC  Allow ACCESS or CONNECT
                Arg 0/   Error block address
                Arg 1/   Flags from ACESS JSYS
                Arg 2/   Directory number

20      .GOOAD  Allow assign due to OPENF
                Arg 0/  Error block address
                Arg 1/  Device designator

400000+n        Customer Reserved Functions
                Arg 0/  Error block address

Error Block Format:

        Word 0/ Number of words in this block (including this word)
        Word 1/ Error Number
        Word 2/ Byte Pointer to error string location
        Word 3/ Maximum bytes user can accept in error string

The GETOK JSYS requests permission to perform the specified function.
An  access  control  program,  if  running,  does  a  RCVOK and reads
information about the request.  Some  data  about  the  requestor  is
provided automatically for all functions;  in addition RCVOK provides
a copy of the argument block given to GETOK.  See RCVOK for a list of
common  data.   If  no access control program is running, the monitor
takes a default action.  See TMON for a list of defaults.

Success from the GETOK JSYS does not provide  the  action  requested;
it simply permits it.
To:  Monitor Attendees List                                    Page 4


1.  User supplies all arguments in argument block.  In  error  block,
the  user  supplies  offsets  0,  2,  and  3.   If an error string is
provided by the program doing the GIVOK, the byte pointer  and  count
are  updated.   If  the  user is not interested in the reason for the
rejection, the address of the error block can be  0.   If  the  error
block  is  less  than 4 words, only the available words will be used.
If the byte pointer is 0, no string will be returned.

2.  Error codes are of  the  form  1B18+n.   They  are  not  standard
TOPS-20 error codes and therefore cannot be given to ERSTR to produce
a string.  The access control job must supply  a  string  if  one  is

3.  *** For now, even if the GIVOK is given  indicating  success,  an
error string, if present, is copied to the user.  ***

4.  * * * Need a symbol for user functions.

5.  Data for user functions is defined by the access control program.
However,  offset  0  is  reserved for the address of the error block,
which may be 0.
To:  Monitor Attendees List                                    Page 5


Accepts in AC1/ Request Number  (from RCVOK message)
           AC2/  0 = request granted,   
                1B18+error number = request denied      
           AC3/ pointer to ASCIZ string (max 40 characters) or 0.

        GIVOK   (requires WHEEL or OPERATOR)

Returns +1:     Always

Causes an illegal instruction trap under certain conditions.
To:  Monitor Attendees List                                    Page 6


Accepts in AC1/ Address of Argument Block 
           AC2/ Length of Argument Block
        RCVOK   (requires WHEEL or OPERATOR)

Returns +1      Always

Causes an illegal instruction trap under certain conditions.


        Word 0/ Function Code,,Job Number of Requestor
        Word 1/ User Number
        Word 2/ Connected Directory
        Word 3/ Request Number
        Word 4/ # args passed,,# user-supplied args
        Word 5/ Address of user-supplied args
        Word 6/ Capabilities enabled
        Word 7/ Controlling Terminal Number
        Word 10/ Requested Job Number
        Word 11/ Offset 0 in function-dependent data
        Word 11+n/ Offset n in function-dependent data

This JSYS provides to the caller information about one GETOK request.
The monitor fills in all words of the argument block. It stores
function-independent data in the first 10 words. It copies into the
11th and following words the argument block that was provided by the
caller of GETOK.


1. If the user wishes to reject the requested access, the program
returns an error code in AC 2. It can also provide an error string,
which is copied to the caller of GETOK if the caller has provided
a pointer for it.

2. Offset 7 contains a terminal number, not a device designator.
To:  Monitor Attendees List                                    Page 7

New SMON Function

Accepts in AC1/ .SFSOK          ;Set OK defaults
           AC2/ Flags ,, GETOK Function Code

Returns +1:     Always

        1B0     SF%EOK  1 = Enable access checking      
                        0 = Disable access checking     

        1B1     SF%DOK  1 = Allow access if checking disabled
                        0 = Deny access if checking disabled

This function should be given by the access control job  to  turn  on
access  checking  for  each of the desired functions.  It can also be
used to set the default action for each function that  is  not  being
checked by the access control job.  This function can only be used to
set  the  defaults  for  system  function  codes.   Customer  defined
function  codes  (400000+n) will always have access checking enabled.
If there is no access control job, the default action  of  the  GETOK
JSYS  will be to always deny access for any customer defined function


1.  To enable user functions, provide an access code of 400000.
To:  Monitor Attendees List                                    Page 8

New TMON Function

Accepts in AC1/ .SFSOK
           AC2/ GETOK Function Code


Returns +1:     Always,
                AC2/    Flags ,, Function Code

The flags are the same as those described in the SMON description.

Default action settings for each function code:

Allow   .GOASD  Assign a device
Allow   .GOCAP  Enable capabilities
Allow   .GOCJB  Allow CRJOB JSYSs
Allow   .GOLOG  Allow LOGINs
Allow   .GOCFK  Allow CFORK JSYSs
Allow   .GOTBR  Set terminal baud rate
Allow   .GOLGO  Allow logout when over quota
Deny    .GOENQ  Set ENQ quota
Allow   .GOCRD  Allow directory creation
Allow   .GOSMT  Allow smount
Allow   .GOMDD  Allow mddt entry
Allow   .GOCLS  Set class of job
Allow   .GOCL0  Set class at LOGIN
Deny    .GOMTA  Verify labeled tape access
Allow   .GOOAD  Allow ASSIGN due to OPENF

Deny    400000+n        Customer definable functions
To:  Monitor Attendees List                                    Page 9


1)      Each GETOK JSYS causes an GETOK request to be queued for  the
        access  control  job.   The  access  control job will have to
        issue a RCVOK JSYS.

2)      The process executing the GETOK will then block, waiting  for
        the GIVOK to be returned by the access control job.

3)      The access control job decides to grant or deny this  request
        and  issues  the  GIVOK  JSYS with the appropriate answer for
        this request.

4)      The requesting process is unblocked, and removes the  request
        block   from  the  GETOK  request  queue  and  is  given  the
        appropriate return.