Understanding SAF › Defining Environments for SAF Calls (SAFDEF)

Defining Environments for SAF Calls (SAFDEF)

The SAFDEF record defines the SAF environment and how you want
CA ACF2 for VM to process the SAF call. CA ACF2 for VM provides internal SAFDEFs for SAF default protection. To see a list of the SAFDEF records active on your system, see the Viewing SAFDEF Records.

CA ACF2 for VM processes all SAF calls by default. To override the default SAF processing for a specific security event, you can specify a SAFDEF record. We provide examples of how to override SAFDEF records in Solving Problems with SAF Calls later in this chapter. CA ACF2 for VM performs validation based on the environment you define in this record. SAFDEF records are processed in a specific sorted order based on fields in the record, whether it is an external or internal SAFDEF, and whether the SUBSYS is defined as ACF2 or VMO. The sort criteria is as follows:

1. Record key
2. JOBNAME (Service machine name)
3. USERID
4. PROGRAM (Not active for VM sites)
5. RB (Not active for VM sites)
6. REQSTOR (RACROUTE parameter)
7. SUBSYS (RACROUTE parameter)
8. REQUEST (RACROUTE parameter)
9. SAFDEF (INTERNAL or EXTERNAL)
10. SUBSYS (ACF2 or VMO)

The only RACROUTE parameter that is used on the sort is REQUEST. See the following pages for specific information on each of these fields.

A description of the record format and fields of the SAFDEF record follows:

Fields

ID(name)

Specifies an ID name associated with the record. You can specify up to eight characters. This field is optional. We recommend you specify an ID because this name will appear as the first field displayed in the SHOW SAFDEF output. The ID is also the key used for the SHOW SAFDEF subcommand.

Select a name that is unique and that conveys meaning about the type of SAF call you are defining. For example, VERSMS would be an appropriate ID for a SAFDEF record that defines the environment for a REQUEST=VERIFY call from DFSMS.

FUNCRET(4|retcode)

Specifies the SAF function‑dependent return code returned to the caller making the RACROUTE request when MODE is specified as IGNORE. For detailed descriptions of possible return codes, see the IBM document entitled External Security Interface (RACROUTE) Macro Reference Guide. The default is four.

FUNCRSN(0|retcode)

Specifies the SAF function‑dependent reason code to be returned to the caller making the RACROUTE request when MODE is specified as IGNORE. For detailed descriptions of possible reason codes, see the IBM document entitled External Security Interface (RACROUTE) Macro Reference Guide. The default is zero.

JOBNAME(mask|********)

Specifies the user ID of the service machines that apply to this SAFDEF record. You can specify an eight‑character user ID or a mask. The default is all service machines.

MODE(IGNORE|GLOBAL|LOG|QUIET)

Specifies the mode you want CA ACF2 for VM to use to process this SAF request. This field defaults to GLOBAL; a value is required. You can specify any one of the following values:

IGNORE

Bypass processing this SAF request

GLOBAL

Process this SAF request using the mode specified in the VMO OPTS record. For generalized resource validations, use the CA ACF2 for VM recommendation to allow or deny the SAF request.

LOG

Process this REQUEST=AUTH call in LOG mode.

QUIET

Process this REQUEST=AUTH call in QUIET mode.

PROGRAM(mask|********)

This field is not active for VM sites. For more information for this field, see the CA ACF2 for VM for z/OS Administrator Guide.

RACROUTE(keyword=value,...,keyword=value)

Identifies the SAF request being made. Use this field to specify any valid RACROUTE parameters and values. This is a multi‑value field. The maximum length that you can specify for the parameter keyword, operator, and value is 64 characters. Separate the entries with commas or blanks. The REQUEST= keyword is required.

You can specify the following relational operators to indicate the presence of a particular value (for example, ENVIR=CREATE) or the presence of a pointer address (ACEE=<). You can use the following operators depending on your type of keyboard:

=   Equal to
¬=  Not equal to
><  Not equal to
!=  Not equal to
=<  Pointer value
¬=<  No pointer value
!=<  No pointer value

Pointer values are valid only if the keyword operand is specified as a pointer to a data area or data structure (for example, ACEE). When you specify a pointer value, do not also specify a value for the operand. For example, the following request defines a VERIFY request for all user IDs except JOHN, where an ACEE is supplied:

RACROUTE(REQUEST=VERIFY,ACEE=<,USERID>notsym.=JOHN)

You can mask character data types using the standard CA ACF2 for VM masking characters (asterisk and dash). You can mask other types of data only if the mask is complete. A complete mask indicates that the parameter matches all values. For example, you can specify the following to indicate that this parameter matches all values of USERID:

USERID=‑

Whereas, the following indicates that the USERID option does not apply to this RACROUTE request:

USERID>notsym.=‑

Note: There are SAFDEF restrictions with FASTAUTH processing. FASTAUTH does not allow the use of ENTITY on the RACROUTE field of the SAFDEF.

RB(mask|********)

This field is not active for VM sites. For more information for this field, see the CA ACF2 for VM for z/OS and OS/390 Administrator Guide.

RETCODE(0|4|8)

Specifies the SAF return code to be returned to the caller making the RACROUTE request when MODE is specified as IGNORE.

0

Allow the request.

4

Let the caller decide how to process the request. This is the default.

8

Deny the request.

USERID(useridmask|********)

Specifies the user ID that applies to this SAFDEF record. The default is all user IDs.