QUERY SECURITY

The effect of SIT parameters on QUERY SECURITY commands

Description

The QUERY SECURITY command allows the application to determine whether a user has access to resources defined in RACF. These resources can be in CICS resource classes or in user-defined resource classes.

Before CICS calls RACF, for all resources except PSBs, CICS checks that the resource is installed. If the resource does not exist, CICS does not call RACF and returns the NOTFND condition.

If USERID is not specified, the user to be queried is the user that invokes the transaction that issues the QUERY SECURITY command.

Alternatively, the application can query the security authorization of a different user that is specified in the USERID option.

For information about querying access from an application, see Application-specific security (QUERY SECURITY).

Options

ALTER(cvda)

Query whether the user has ALTER authority for the named resource. The CVDA values that are returned by CICS are ALTERABLE and NOTALTERABLE.

CONTROL(cvda)

Query whether the user has CONTROL authority for the named resource. The CVDA values that are returned by CICS are CTRLABLE and NOTCTRLABLE.

LOGMESSAGE(cvda)

Inhibit security violation messages. The values passed to CICS are LOG (the default value), or, to inhibit messages, NOLOG.

READ(cvda)

Query whether the user has READ authority command for the named resource. The CVDA values that are returned by CICS are READABLE and NOTREADABLE. READ access authority usually permits nondestructive use of a resource as, for example, in the case of READ and INQUIRE commands.

RESCLASS(data-value)

Use this option to query access levels for non-CICS resources. To query access to CICS resources, you should normally use the RESTYPE option, where the resource class is determined by the corresponding Xnnn system initialization parameter. However, if, for special reasons, you want to inquire about specific CICS resource classes, the class name must be the member class, not the group class; that is, CCICSCMD, not VCICSCMD. The profiles in the group class are checked automatically if the member class is activated by RACLIST. CICS can RACLIST groups only if the relevant Xnnn classes are active (for example, XCMD=YES or XCMD=$USRCMD). For example, if SEC=YES, and XCMD=YES are specified, both CCICSCMD and VCICSCMD are activated by RACLIST in the CICS region, which means that QUERY SECURITY RESCLASS('CCICSCMD') checks profiles in both CCICSCMD and VCICSCMD.

Specifies an 8-character field that identifies the name of a valid RACF resource class, which might be non-CICS, in RACF. . If you specify RESCLASS, you must also specify both RESID and RESIDLENGTH.

The RACF class can be CICS-supplied or user-defined. RESCLASS enables you to define more narrowly the authorization to be queried; for example, you can query at the record or field level. The class name that is identified by RESCLASS is treated literally with no translation. The RACF classes DATASET, GROUP, and USER do not appear in the class descriptor table (CDT), which means that you cannot query against these classes.

You can also use the RESCLASS option for querying access to DB2ENTRY resources defined in a user-defined resource class, which you specify to CICS on the XDB2 system initialization parameter. The rules about activating classes by using the RACLIST command also apply to DB2ENTRY resource classes named on the XDB2 system initialization parameter. See Resource classes for DB2ENTRY resources.

To query a user's surrogate authority, you can use the QUERY SECURITY command with the RESCLASS('SURROGAT') option. You also need to specify the RESID and RESIDLENGTH options. However, this command is not controlled by the XUSER system initialization parameter, so you might obtain an unexpected response of NOTREADABLE if XUSER=NO is specified. For example, to check whether the current user is allowed to start a transaction with a new userid of NEWUSER, when XUSER=YES is specified, issue the command:

QUERY SECURITY RESCLASS('SURROGAT') RESID('NEWUSER.DFHSTART')
RESIDLENGTH(16)  READ(read cvda) 

The responses that are returned by the command reflect the definition of the RESID resource as defined in the specified RESCLASS.

If SEC=NO is specified in the system initialization parameters, QUERY SECURITY RESCLASS always returns READABLE, UPDATABLE, CTRLABLE and ALTERABLE.

RESID(data-value)

Specifies the name of the CICS or user-defined resource that you want to query the users access to. The value is a character string (1 - 12 characters for a CICS resource, and 1 - 246 characters for a user-defined resource, unless you are using the COBOL3 translator option in which case the maximum length is 160 characters). RESID refers to a CICS-defined resource only when RESTYPE('SPCOMMAND') is specified; otherwise, it refers to a user-defined resource.

The maximum length of a resource (RESID) in a RACF class is defined in the class descriptor table (CDT). When defining RESID values, be aware of the effects of using blanks (X'40') in resource identifiers. For example, in QUERY SECURITY RESTYPE('PSB') RESID('A B'), the blank delimits the RESID and causes RACF to use a resource name of A. Similarly, in QUERY SECURITY RESCLASS('MYCLASS') RESID('MY PROFILE') RESIDLENGTH(10), the presence of a blank causes an INVREQ condition. This is because RACF does not allow blanks to be embedded in a profile name.

The actual resource that is checked depends on whether RESCLASS or RESTYPE is specified in the command and (for RESTYPE only) whether prefixing is active (SECPRFX=YES or SECPRFX=prefix specified as a system initialization parameter).

Table 2. What resource is checked?

Option	Effect of prefixing	SECPRFX=YES	SECPRFX=prefix	SECPRFX=NO
RESCLASS	None. The specified RESID value is checked. CICS does not prefix the RESID with the CICS-region user ID, nor with a user-specified prefix, before it calls RACF.	n/a	n/a	n/a
RESTYPE	Depends on the setting of SECPRFX system initialization parameter.	The RESID value prefixed with the CICS region user ID	The RESID value prefixed with the prefix that is specified on SECPRFX.	The specified RESID value

For example, if you issue the following command QUERY SECURITY RESTYPE('FILE') RESID('PAYFILE'),

• When SECPRFX=YES, CICS applies the CICS region user ID as a prefix, and calls RACF to check the user's access to cics-region-userid.PAYFILE.
• When SECPRFX=prefix, CICS applies the prefix that is supplied, and calls RACF to check the user's access to prefix.PAYFILE.
• If SECPRFX=NO is specified, CICS does not apply a prefix, and calls RACF to check the user's access to PAYFILE.

When RESTYPE('SPCOMMAND') is specified, the identifiers are predetermined by CICS. The list of possible resource identifier (RESID) values for SPCOMMAND is listed in the table of CICS resources subject to command security checking.

RESIDLENGTH(data-value)

Specifies the length, as a fullword binary, of the resource identifier in RESID. You only use this parameter when specifying the RESCLASS option. The maximum length of a resource (RESID) within a RACF class is specified in the class descriptor table (CDT).

RESTYPE(data-value)

Use this option to query the access level of a user to types of CICS resource (including Db2® resource definitions) contained in the classes activated at initialization by RACLIST. Specify the type of resource 1 - 12 characters.

If the resource is not defined to RACF®, CICS does not grant access and the response is NOTREADABLE. Ensure the length of the resource name passed to RACF with a RESTYPE request is the actual maximum length for that resource type.

The value that you specify for RESTYPE must be one of the following resource types:

Table 3. QUERY SECURITY RESTYPE values

RESTYPE value	Xnnn parameter
ATOMSERVICE	XRES
BUNDLE	XRES
DB2ENTRY	XDB2
DOCTEMPLATE	XRES
EPADAPTER	XRES
EPADAPTERSET	XRES
EVENTBINDING	XRES
FILE	XFCT
JOURNALNAME	XJCT
JOURNALNUM (supported for compatibility with previous releases)	XJCT
JVMSERVER	XRES
PROGRAM	XPPT
PSB	XPSB
SPCOMMAND (used to specify a CICS-defined resource for a command)	XCMD
TDQUEUE	XDCT
TRANSACTION	XPCT
TRANSATTACH	XTRAN
TSQUEUE	XTST
TSQNAME	XTST
XMLTRANSFORM	XRES
n/a	XHFS

The XHFS system initialization parameter controls resource security for zFS files and does not have a corresponding RESTYPE value on the QUERY SECURITY command. Access controls for zFS files follow the system of permissions that are used by z/OS UNIX System Services, so they operate in a different way.

With dynamic transaction routing, you do not have to install transaction definitions in terminal owning regions. A QUERY SECURITY command with a RESTYPE of TRANSATTACH returns the NOTFND condition if the transaction is not installed. Application developers must be aware that the transaction might be routed dynamically.

If you issue QUERY SECURITY RESTYPE(TRANSATTACH) RESID(tranid) READ(cvda), this command returns the CVDA value of READABLE if the user has READ authority for the resource with the name tranid, but NOTREADABLE if the user has only EXECUTE authority. Therefore, applications that use QUERY SECURITY RESTYPE(TRANSATTACH) to build a menu of available transactions will not work if EXECUTE authority is used.

The responses that are returned by the command reflect the results that would be obtained if an actual attempt was made to access the specified CICS resource.

UPDATE(cvda)

Query whether the user has UPDATE authority for the named resource. The CVDA values that are returned by CICS are UPDATABLE and NOTUPDATABLE. UPDATE access authority usually permits destructive use of a resource as, for example, in the case of WRITE, DELETE, or UPDATE commands.

USERID(data-value)

Specifies the 8-character user ID of the user whose access to the specified resources is queried.

The user who invokes the transaction that issues the QUERY SECURITY command must have the authority to query whether another user as specified in USERID has access to the specified resource. CICS performs a surrogate user check to verify whether the execution user that invokes the transaction is authorized to the surrogate user specified in USERID. If the surrogate user check fails, CICS returns a NOTAUTH condition.

Conditions

16 INVREQ

RESP2 values:

7

The CVDA value is not valid for the LOGMESSAGE.

9

The RESID is invalid or filled with blanks.

10

RACF is inactive or not present.

6.2 13

One of the access levels (READ, UPDATE, CONTROL, or ALTER) must be specified.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

6

The RESIDLENGTH value is not valid, that is, not in the range 1 - 246.

Default action: terminate the task abnormally.

70 NOTAUTH

RESP2 values:

102

The surrogate user security check on the specified USERID fails.

The security access capabilities of the transaction that issued the command do not allow the command to be performed with the value specified in the USERID option.

The security access capabilities of the transaction are established by RACF according to the user security, and whether link security or the execution diagnostic facility (EDF) has been in use.

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

1

The RESID is not valid.

2

The RESTYPE is not valid.

3

The RESID value for RESTYPE (SPCOMMAND) is not valid.

5

The RESCLASS is not defined to RACF.

8

The resource is not protected. This is only returned when QUERY SECURITY is used with the RESCLASS option (and never occurs with RESTYPE).

Possible causes include:

• RESCLASS not active.
• No profile found.
• ESM not active.

Default action: terminate the task abnormally.

44 QIDERR

RESP2 values:

1

An indirect queue name that is associated with the given RESID is not found.

Default action: terminate the task abnormally.

69 USERIDERR

RESP2 values:

11

The specified USERID is not known to RACF.

12

The specified USERID is revoked.

QUERY SECURITY logging options

You can control logging on the QUERY SECURITY command. When logging is in effect, if the terminal user does not have the requested access to the specified resource, messages DFHXS1111 and DFHXS1117 are issued to the CICS security transient data destination CSCS. Where relevant, RACF message ICH408I is also issued.

SMF records can also be recorded, depending on the auditing and logging options that have been specified for that resource. For more information, see the z/OS Security Server RACF Auditor's Guide .

6.2 For auditing purposes, when logging is disabled, CICS statistics are still written to XSG_AUTHOR_FAIL_NL_NA (DFHSTUP name Failed authorizations NOLOG NOTAUTH) and XSG_AUTHOR_FAIL_NL_NF (DFHSTUP name Failed authorizations NOLOG NOTFND) fields. And monitoring data is written to XSNLNACT and XSNLNFCT fields. For more information, see Security domain: Global statistics and Performance data in group DFHTASK.

For programming information about CVDAs, refer to CICS-value data areas (CVDAs).

Examples of values returned by QUERY SECURITY=RESTYPE

SEC=NO

When SEC=NO is specified, issuing:

QUERY SECURITY RESTYPE('FILE') RESID('PAYFILE') ALTER(alter_cvda)

returns:

alter_cvda = DFHVALUE(ALTERABLE)

because SEC=NO means that no security checking is done for the entire CICS region.

SEC=YES and XFCT=NO

When SEC=YES and XFCT=NO are specified, issuing:

QUERY SECURITY RESTYPE('FILE') RESID('PAYFILE') ALTER(alter_cvda)

returns:

alter_cvda = DFHVALUE(ALTERABLE)

because XFCT=NO means that no security checking is done for files.

SEC=YES, XDCT=YES, and SECPRFX=NO

When SEC=YES, XDCT=YES, and SECPRFX=NO are specified, issuing:

QUERY SECURITY RESTYPE('TDQUEUE') RESID('TDQ1') READ(read_cvda)

returns:

read_cvda = DFHVALUE(READABLE)

if the user has READ (or higher) access to 'TDQ1' in the DCICSDCT class or the ECICSDCT group class.

SEC=YES, XTRAN=YES, and SECPRFX=YES

When SEC=YES, XTRAN=YES, and SECPRFX=YES are specified, issuing:

QUERY SECURITY RESTYPE('TRANSATTACH') RESID('TRN1') READ(read_cvda)

returns:

read_cvda = DFHVALUE(NOTREADABLE)

if the user does not have READ (or higher) access to cics_region_userid.TRN1 in the TCICSTRN class or GCICSTRN group class.

SEC=YES, XTRAN=YES, and SECPRFX=YES

When SEC=YES, XTRAN=YES, and SECPRFX=YES are specified, issuing:

QUERY SECURITY RESTYPE('TRANSATTACH') RESID('TRN1') READ(read_cvda)

returns:

read_cvda = DFHVALUE(NOTREADABLE)

if the user does not have READ (or higher) access to cics_region_userid.TRN1 in the TCICSTRN class or GCICSTRN group class.

SEC=YES, XCMD=$USRCMD, and SECPRFX=prefix

When SEC=YES, XCMD=$USRCMD, and SECPRFX=prefix are specified, issuing:

QUERY SECURITY RESTYPE('TRANSATTACH') RESID('TRN1') READ(read_cvda)

returns:

read_cvda = DFHVALUE(NOTREADABLE)

if the user does not have READ (or higher) access to prefix.TRN1 in the TCICSTRN class or GCICSTRN group class.