KnowledgeBase 00050: Security Subroutines

This article was originally published as a Tip of the Week.

Security subroutines can be used to control access to specific commands.

The Security Subroutine

A security subroutine is a user-written Basic subroutine that will be executed automatically when an application attempts to execute the VOC item to which it applies

In QM, the declaration of this subroutine is

   SUBROUTINE XXX(OK, VERB, REMOTE.FILE, REMOTE.ID)

where

XXX	is the name of the subroutine
OK	is used to return a Boolean result indicating whether the command should be run.
VERB	is the name of the VOC item being processed.
REMOTE.FILE	is the name of the file referenced by the R-type VOC item. This is a null string for a V-type item.
REMOTE.ID	is the record id referenced by the R-type VOC item. This is a null string for a V-type item.

The subroutine may perform any checks it wishes to determine whether the user is allowed to execute the command. This might be based on, for example, the user's login id, the IP address of a network connection, the UID or GID of a Linux/Unix process, the time of day, etc.

The subroutine should return the OK argument as true (1) if the command can be run, false (0) if the user is to be denied access.

R-type VOC Items

An R-type VOC record points to an executable item (verb, sentence, paragraph, menu, etc) in another file.

   1:  R 
   2:  File name 
   3:  Record name 
   4:  Security subroutine name

Field 4 is optional and, if present, holds the name of the catalogued security subroutine. Using the name of the R-type item as a command will execute the subroutine to determine whether the action should continue. If it is allowed, the command processor follows the link to the remote record and executes it.

V-type VOC Items

Security subroutines can be applied directly to V-type VOC items by placing the subroutine name in field 5, avoiding the need for a separate entry in another file. The subroutine will be called in exactly the same way as for the R-type record described above.

Making it Water-Tight

Clearly, if the aim is to restrict the activity of a user who has access to the QM command line, it is necessary to include security subroutines on all VOC items that might allow the user to edit the VOC, removing the security subroutine name. Alternatively, ensure that the user does not have write access to the VOC.

Auditing and Debugging

Although security subroutines are intended for restricting access to specific commands, they are also very useful for auditing and debugging purposes.

In this case, the subroutine should always return the OK argument as true but can log details of how the command is being executed. This might be the username, IP address, or other information identifying the user. Alternatively, it could be the detailed call stack as returned by the SYSTEM(1002) function.