13.1. Calls to the Security Manager

When the language processor reaches any of the defined security checkpoints, it sends a message to the security manager for the particular checkpoint. The message has a single argument, a directory of information that pertains to the checkpoint. If the security manager chooses to handle the action instead of the language processor, the security manager uses the checkpoint information directory to pass information back to the language processor.

Security manager methods must return a value of either .false or .true to the language processor. A value of .false indicates that the program is authorized to perform the indicated action. In this case, processing continues as usual. A value of .true indicates that the security manager performed the action itself. The security manager sets entries in the information directory to pass results for the action back to the language processor. The security manager can also use the RAISE instruction to raise a program error for a prohibited access. Error message 98.948 indicates authorization failures.

The defined checkpoints, with their arguments and return values, are:

CALL

sent for all external function calls. The information directory contains the following entries:

NAME: The name of the invoked function.
ARGUMENTS: An array of the function arguments.

When the CALL method returns .true, indicating that it handled the external call, the entry RESULT (if any) in the information directory is used as the function call result.

COMMAND

sent for all host command instructions. The information directory contains the following entries:

COMMAND: The string that represents the host command.
ADDRESS: The name of the target ADDRESS environment for the command.

When the COMMAND method returns .true, indicating that it handled the command, the security manager uses the following information directory entries to return the command results:

RC: The command return code. If the entry is not set, a return code of 0 is used.
FAILURE: If a FAILURE entry is added to the information directory, a Rexx FAILURE condition is raised.
ERROR: If an ERROR entry is added to the information directory, a Rexx ERROR condition is raised. The ERROR condition is raised only if the FAILURE entry is not set.

REQUIRES

sent whenever a ::REQUIRES directive in the file is processed. The information directory contains the following entry:

NAME: The name of the file specified on the ::REQUIRES directive.

When the REQUIRES method returns .true, indicating that it handled the request, the entry NAME in the information directory is used as the actual file to load for the request. The REQUIRES method can also provide a security manager to be used for the program loaded by the ::REQUIRES directive by setting the information directory entry SECURITYMANAGER to the desired security manager object.

LOCAL

sent whenever Rexx is going to access an entry in the .LOCAL directory as part of the resolution of the environment symbol name. The information directory contains the following entry:

NAME: The name of the target directory entry.

When the LOCAL method returns .true, indicating that it handled the request, the information directory entry RESULT contains the directory entry. When RESULT is not set and the method returns .true, this is the same as a failure to find an entry in the .LOCAL directory. Rexx continues with the next step in the name resolution.

ENVIRONMENT

sent whenever Rexx is going to access an entry in the .ENVIRONMENT directory as part of the resolution of the environment symbol name. The information directory contains the following entry:

NAME: The name of the target directory entry.

When the ENVIRONMENT method returns .true, indicating that it handled the request, the information directory entry RESULT contains the directory entry. When RESULT is not set and the method returns .true, this is the same as a failure to find an entry in the .ENVIRONMENT directory. Rexx continues with the next step in the name resolution.

STREAM

sent whenever one of the Rexx input and output built-in functions (CHARIN, CHAROUT, CHARS, LINEIN, LINEOUT, LINES, or STREAM) needs to resolve a stream name. The information directory contains the following entry:

NAME: The name of the target stream.

When the STREAM method returns .true, indicating that it handled the request, the information directory entry STREAM must be set to an object to be used as the stream target. This should be a stream object or another object that supports the Stream class methods.

METHOD

sent whenever a secure program attempts to send a message for a protected method (see the ::METHOD directive Section 3.5, “::METHOD”) to an object. The information directory contains the following entries:

OBJECT: The object the protected method is issued against.
NAME: The name of the protected method.
ARGUMENTS: An array containing the method arguments.

When the METHOD method returns .true, indicating that it handled the request, the entry RESULT (if any) in the information directory is used as the method result.