SirSafe command and function reference
SirSafe is controlled by enhancements to the AUTHCTL command, and it provides its services through extensions to other Model 204 commands, including LOGCTL, LOGFILE, LOGGRP, and SECURE. SirSafe also offers subsystem maintenance commands and a $function that provides an interface to an external authorizer.
All of these controls are described on this page.
AUTHCTL
The AUTHCTL command is used to activate SirSafe for a Model 204 password table and to control various aspects of its function. The basic AUTHCTL command is described in the Model 204 Security interfaces pages. This section describes only additions and extensions specific to SirSafe.
AUTHCTL A SIRSAFE
The AUTHCTL A SIRSAFE command is used both to
activate SirSafe for a Model 204 password table and to specify the
security environments that are allowed to access the password table.
This is accomplished by adding a SirSafe security entry that is processed during Model 204 initialization.
Syntax
AUTHCTL A SIRSAFE { OPTIONAL | REQUIRED } [ MVSRW | MVSRO ] - interface=mask [interface=mask] ...
Syntax terms
| OPTIONAL | Indicates that the current Model 204 password table will be accessible to any Model 204 Online, including those without SirSafe support.
However, no visible file or group entries may be added to a password table when SirSafe support is optional. Note: If a SirSafe-enabled Model 204 instance opens a password table that has been set as optional, SirSafe will activate only if the current security environment satisfies the conditions described by the SirSafe security entry. |
|---|---|
| REQUIRED | Indicates that the current Model 204 password table will only be accessible to a Model 204 online that has:
|
| MVSRW | Indicates that Model 204 will try to open all files in read/write mode and update their FPL pages, even if the file is being opened for read/only access. If a file cannot be opened in read/write mode, it will not be opened. This is the standard Model 204 behavior, and it is the default. |
| MVSRO | Indicates that if Model 204 is not allowed to open a file in read/write mode, it will try to open it in read/only mode and so not update theFPL page of the file. Whether or not Model 204 is allowed to open afile in read/write mode depends, of course, on the security profile of the user under which theModel 204 job is running. |
| interface | The name of a Model 204 external security interface: RACF, ACF2, or TOPSECRET. |
| mask | A character string that identifies an acceptable environment for the corresponding security interface, as described further, below. You can use a trailing asterisk (*) to identify a range of possible environments. |
Usage notes
Multiple interface=mask pairs may be specified. During initialization, a SirSafe-enabled Model 204 scans the password table for a SirSafe security entry. If one is found, its list of interface=mask pairs is checked. If an entry matching the current security environment is found, Model 204 enters the SirSafe-active state. Otherwise an M204.0340 or M204.0341 error message is produced.
The interpretation of interface and mask combinations depends upon the particular interface:
- For RACF, the mask value applies to the field identified as the "RACF CONTROL GROUP NAME" on an AUTHCTL VIEW command (see the example in AUTHCTL VIEW).
- For ACF2, the mask value applies to the field identified as the
"ACF2 RESOURCE TYPE" on an AUTHCTL VIEW command,
prefixed with the letter
R. - For TOPSECRET, the mask value applies to the field identified as the "ACID" on an AUTHCTL VIEW command.
Thus, the following command allows visible file and group passwords to be stored and requires that Model 204 be SirSafe-enabled when it tries to use the password table:
AUTHCTL A SIRSAFE REQUIRED RACF=M204* - ACF2=R204 TOPSECRET=*
If RACF was being used, the RACF control group could be any
name starting with M204, which would include the default M204RACF.
If ACF2 was being used, the ACF2 resource type would need to be 204, which is the default.
And any CA-Top Secret environment would be allowed.
AUTHCTL C SIRSAFE
The AUTHCTL C SIRSAFE command is used to change the SirSafe security entry for a Model 204 password table. It accepts the same parameters as the AUTHCTL A SIRSAFE command. It is especially useful for updating the security masks for a password table that contains visible file or group entries.
The AUTHCTL C SIRSAFE command may not be used to switch a password table to the SirSafe-optional state if the table contains any visible file or group entries. An MSIR.0542 error message is produced, and the command is ignored.
AUTHCTL D SIRSAFE
The AUTHCTL D SIRSAFE command is used to delete the SirSafe security entry from a Model 204 password table, deactivating SirSafe.
Any visible file and group entries must be deleted before SirSafe can be deactivated.
If the current SirSafe security entry includes the REQUIRED
attribute, and visible file or group password entries have been
added to the password table, an AUTHCTL D request will be rejected
with an MSIR.0542 error message.
AUTHCTL LIST SIRSAFE
The AUTHCTL LIST SIRSAFE command is used to list the SirSafe security entry, if any in the current Model 204 password table. The output from this command is the AUTHCTL A SIRSAFE command that could be used to recreate the SirSafe security entry. For example:
AUTHCTL LIST SIRSAFE AUTHCTL A SIRSAFE REQUIRED MVSRO RACF=M204*
AUTHCTL REFRESH
The AUTHCTL REFRESH command causes Model 204 to manually rebuild its list of systems for which enhanced shared DASD enqueueing is active, including whether the systems are visible or have become invisible. This list is displayed by the AUTHCTL VIEW command, as described in Controlling shared DASD enqueueing.
Syntax
AUTHCTL REFRESH [CLEAR]
The CLEAR option directs Model 204 to remove from its list any systems that were once visible, but are now invisible.
Usage notes
If a Model 204 instance is started without a copy of SIRENQ running, an AUTHCTL REFRESH command is required to enable enhanced shared DASD enqueueing.
AUTHCTL TEST
The AUTHCTL TEST command is used to activate or deactivate the logging of SirSafe debugging and diagnostic information. When the AUTHCTL TEST facility is active, informative messages are produced that track the various calls SirSafe makes to the current security interface. The SirScan product may be used to examine the messages, or they may be retrieved with the Model 204 VIEW ERRORS command.
Note: If using VIEW ERRORS, remember that the most recent messages are listed first.
Syntax
AUTHCTL TEST { ON | OFF }
Usage notes
AUTHCTL TEST ONproduces six informational messages to the journal and Model 204 operator. If the MVSRO feature is active, two messages are used to track the tests performed to determine access to Model 204 database file data sets, as shown in Monitoring and debugging. The remaining four messages are for debugging access to file and group passwords.- If no security environment is active, SirSafe produces an
MSIR.0552message, and access to file and group passwords is disallowed. Otherwise, anMSIR.0553message is produced for each file or group password table entry that matches a password provided by a user, indicating that SirSafe is testing the current end user's access. If the external security interface disallows the requested access, anMSIR.0554message is produced. If the requested access is allowed by the external security interface, anMSIR.0557message is produced. - The
MSIR.0553message identifies the user attempting the access, the "dataset" name associated with the access, and the type of access required (read or write). The user ID is identified in two ways: the Model 204 "internal ID," that is, the ID that appears in messages on the journal, and the external security interface view — including the user ID and group ID. TheMSIR.0553message is the only source of the external authorizer information, which is important for several reasons:- The access checks are performed using the external ID and group.
- The access rights are frequently conferred from group, as opposed to the ID.
- When Model 204 processes a login with an ID from CCASTAT, the external user ID and group are defined by the Model 204 external security interface.
Example
In the following example, user GARY logs in with a CCASTAT ID,
then opens the semi-public file PROCFILE with the password WRITE.
The user does not get the expected access privileges, in fact the user gets the
default privileges for the file:
O PROCFILE *** M204.0347: PASSWORD *** M204.0620: FILE PROCFILE OPENED -- NO UPDATES ALLOWED VIEW ERRORS MSIR.0554: SirSafe disallowed password access MSIR.0553: GARY (M204USR,M204GRP) read to M204RACF.FILE.PROCFILE.INDEXA tried by MSIR.0598: SirSafe: R/W access allowed MSIR.0597: SirSafe: (GARY,SYS1) checking R/W to M204.GARY.PROCFILE on MVS204 V CURPRIV,PRIVDEF CURPRIV X'0761' PRIVS FOR CURRENT FILE/GROUP PRIVDEF X'0761' DEFAULT FILE PRIVILEGES
SirSafe first performed MVS read-only access checking, using the profile for
the Model 204 job (user ID GARY, group SYS1),
and read/write access was allowed, so the file was not opened in read-only mode.
Then the password was matched to the CCASTAT entry for PROCFILE with
index character A, and access to that entry was denied.
Since this was the only password matched (only one MSIR.0553 message), the user was
given the default privileges for the file.
Note: Although the Model 204 internal user ID was GARY, the external profile
being used was user M204USR, group M204GRP.
This occurred because CCASTAT contained an entry for the ID GARY,
a common source of confusion.
AUTHCTL VIEW
The AUTHCTL VIEW command displays the status of the current Model 204 external security interface, if any. If an interface is active, the command displays its type and current execution parameters. If SirSafe is installed, the AUTHCTL VIEW command also displays the status of SirSafe, as the following example shows:
AUTHCTL VIEW RACF INTERFACE OPTIONS GROUP M204RACF RACF CONTROL GROUP NAME COMGROUP M204RAC1 RACF COMMON CONTROL GROUP NAME PRIORITY STANDARD PRIORITY DEFAULT M204GRP DEFAULT USER GROUP M204USR DEFAULT USERID DLMCHECK USE $JOB DLM CHECKING OPTION *** MSIR.0551: SirSafe is active and required for current CCASTAT *** MSIR.0599: SirSafe read-only file checking is active *** MSIR.0687: SirSafe enhanced shared DASD not active, run SirEnq on ZOS4 (P390)
For information about using AUTHCTL VIEW for monitoring enhanced shared DASD enqueueing, see Controlling shared DASD enqueueing.
LOGCTL enhancements for visible file/group entries
SirSafe provides support for visible file and group passwords when it is operated in the REQUIRED mode. Visible file and group entries are easier to administer because all of the data is visible while it is being entered, and because the password value is displayed by a LOGFILE or LOGGRP command.
LOGCTL recognizes standard file entries because the file name is prefixed by a colon (:), and group entries because the name is prefixed by a comma (,). SirSafe extends the LOGCTL A, LOGCTL C, and LOGCTL D commands to support visible file and group entries. Visible file entries are indicated by prefixing the file name with a greater-than sign (>). Visible group entries are indicated by prefixing the group name with a plus sign (+).
Whenever a LOGCTL A or LOGCTL C command is issued for a visible file or group entry, the subsequent line of input is not masked, remaining visible on the System Manager's screen. The following example illustrates how to add a visible file password entry:
logctl a >procfile a M204.0374: ENTER FILE/GROUP PASSWORD,PRIVILEGES,CLASS,SELECT,READ,UPDATE,ADD theman,X'bfff' M204.0379: ENTER TERMINAL LIST, ALL, NONE, ADD, DEL, OR RETURN >PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL M204.0376: PARAMETERS ACCEPTED M204.0345: CCASTAT UPDATED
Note that the password and privileges are visible while typing, and they are echoed to the screen. Also, when the completed entry is listed, the password is displayed. Contrast this to the case for adding a conventional file password:
logctl a :procfile b M204.0374: ENTER FILE/GROUP PASSWORD,PRIVILEGES,CLASS,SELECT,READ,UPDATE,ADD M204.0379: ENTER TERMINAL LIST, ALL, NONE, ADD, DEL, OR RETURN :PROCFILE B ******** X'00FF' 0, 0, 0, 0, 0, ALL M204.0376: PARAMETERS ACCEPTED M204.0345: CCASTAT UPDATED
In the conventional case, the password and privilege line does not echo while typing, and the password is not displayed when the entry is listed.
LOGCTL R
The LOGCTL R command is a SirSafe implemented subcommand for the LOGCTL command. LOGCTL R is used to Replicate (copy) a file or group entry in the password table.
Syntax
LOGCTL R {:filename | >filename | ,grpname | +grpname} [indx]
Where:
| :filename | Indicates a classic, invisible password entry for the named file. |
|---|---|
| >filename | Indicates a visible password entry for the named file. |
| ,grpname | Indicates a classic, invisible password entry for the named group. |
| +grpname | Indicates a visible password entry for the named group. |
| indx | A single index character used to distinguish between multiple entries for a file or group; it defaults to a single space. |
Usage notes
- If the identified entry is found in the Model 204 password table,
the user is prompted for an index character that will identify a new copy of the entry.
Note: The sequence of a
LOGCTL Rfollowed by aLOGCTL Dmay be used to move a file or group entry in the Model 204 password table. - For a simple example of LOGCTL R, see Moving file/group CCASTAT entries.
LOGFILE and LOGGRP enhancements
SirSafe enhances the LOGFILE and LOGGRP commands to facilitate the management of file and group password table entries. These changes are active whenever SirSafe is enabled, whether the SirSafe mode is required or optional.
Viewing visible entries in sorted display
Even though visible file and group entries begin with a different character (>) than their standard counterparts, the file and group sections of the CCASTAT file are sorted in order of file or group name and index character.
logfile procfile >PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL :PROCFILE B ******** X'0761' 0, 0, 0, 0, 0, ALL >PROCFILE 4 THEMAN X'0221' 0, 0, 0, 0, 0, ALL
Note that for visible entries, the value of the password is displayed in clear text, while standard entries are flagged with a field of eight asterisks.
Selecting entries by password
The syntax for LOGFILE and LOGGRP is extended to include a PWDLOCATE option. If the keyword PWDLOCATE is present, the end user is prompted for a password value. That value is used to filter the list of entries that would have been produced without the PWDLOCATE option, and the entries with matching password values is displayed.
LOGFILE PWDLOCATE syntax
LOGFILE [PWDLOCATE] [ [filename1] [filename2] ]
If just one filename is provided, the command lists just the entries for that file. Otherwise, the command lists all the entries that are between the two values, inclusive.
LOGGRP PWDLOCATE syntax
LOGGRP [PWDLOCATE] [ [groupname1] [groupname2] ]
If just one group name is provided, the command lists just the entries for that group. Otherwise, the command lists all the entries that are between the two values, inclusive.
Example
The following example assumes that the user entered theman in response
to the password prompt:
logfile pwdlocate *** M204.0347: PASSWORD >PROCFILE A THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL >PROCFILE 4 THEMAN X'BFFF' 0, 0, 0, 0, 0, ALL
For an additional example using PWDLOCATE, see Identifying file/group CCASTAT entries
SECURE command enhancements
The variant of the SECURE command used to secure a file is extended to accept the qualifier FILE and the optional keyword SIRSAFE:
SECURE FILE syntax
SECURE [[FILE] SIRSAFE]
If the keyword SIRSAFE is present, the current file is set in a mode such that it can only be open when SirSafe is active.
For additional comments about this feature, see Enhanced SECURE command.
Subsystem control commands
For versions of Model 204 prior to 7.5, only sites authorized for SirSafe were allowed to set the APSYSEC parameter. APSYSEC lets a system manager START, STOP, DEBUG, or TEST any subsystem, without having to add the system manager to the SCLASS authorized to do these things.
For sites with Model 204 7.5 and higher, no SirSafe authorization is required for APSYSEC.
$Sir_Check_Access
The $Sir_Check_Access function allows installations to code sophisticated interfaces between Model 204 applications and a System Authorization Facility such as RACF or ACF2. $Sir_Check_Access lets a system security administrator maintain controls over "data set names" that identify intended application actions. By calling the function at strategic points, a SOUL program can provide security with arbitrary granularity.
Note: Use of this function requires purchase of the SirSafe add-on product.
Syntax
%rc = $Sir_Check_Access(dsn, prefix, access, log)
Syntax terms
| %rc | A numeric return code. | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| dsn | An uppercase "data set name," following the usual rules.
Note: If a prefix is provided, the prefix is concatenated to the beginning of dsn with a separating period (.), and the resulting string length must be less than 44 characters. | ||||||||||||||||||
| prefix | A string indicating whether the provided data set name is to be prefixed. Valid values are:
| ||||||||||||||||||
| access | Flag indicating desired access: R for read, or W for write. The default is R. | ||||||||||||||||||
| log | Flag indicating whether failed access checks should be logged: Y or N. The default is N, which suppresses logging. |
Return codes
$Sir_Check_Access returns an integer value, as follows:
| 2 | No authorizer running, call ignored |
|---|---|
| 1 | Access not allowed |
| 0 | Access allowed |
| -1 | Resulting dsname (prefix.dsname) invalid |
| -2 | Prefix argument invalid |
| -3 | Read/write flag invalid |
| -4 | Log/nolog flag invalid |