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: SirSafe support A current security environment that matches one of those specified in the special SirSafe entry This condition enables support for visible file and group entries.
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 ON produces 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.0552 message, and access to file and group passwords is disallowed. Otherwise, an MSIR.0553 message 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, an MSIR.0554 message is produced. If the requested access is allowed by the external security interface, an MSIR.0557 message is produced.
• The MSIR.0553 message 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. The MSIR.0553 message 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 R followed by a LOGCTL D may 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: NONE No prefix is to be provided (the default). AUTH The same HLQ (high-level qualifier) used by SirSafe, determined by the external authorizer in use: RACF The RACF control group name in effect for the run (default M204RACF). ACF2 The character "R" with the ACF2 resource type appended (default R204). TOPSECRET The Top Secret ACID in effect for the run (default M204TOPS). JOB The current job name. JOB.STEP The current job name and step name separated by a period. AUTH.JOB The SirSafe HLQ and job name separated by a period. CCASYS The data set name for CCASYS.
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

See also

• SirSafe
• SirSafe control of access to passwords
• SirSafe support for read-only files under MVS
• SirSafe enhanced shared DASD enqueueing
• SirSafe command and function reference
• SirSafe SIRENQ utility