 |
The standard form of the RACROUTE REQUEST=DIRAUTH macro is written
as follows. For a description of additional keywords that you can
code and additional parameters that are required on the RACROUTE request,
but that are not specific to this request type, see RACROUTE (standard form).
Note: RACROUTE REQUEST=DIRAUTH requires an ACEE under many circumstances.
For most applications, the system will have created an ACEE to represent
the active user. However, for special cases where no ACEE exists,
the invoker must create one before invoking RACROUTE REQUEST=DIRAUTH.
The
most common way to create an ACEE is to issue a RACROUTE REQUEST=VERIFY,
specifying ENVIR=CREATE. After all RACROUTE invocations are complete,
the invoker should issue RACROUTE REQUEST=VERIFY with ENVIR=DELETE
specified, to delete the ACEE previously created.
| |
|
|---|
|
| name |
name: Symbol.
Begin name in column 1. |
| |
|
| ␢ |
One or more blanks must precede RACROUTE. |
| |
|
| RACROUTE |
|
| |
|
| ␢ |
One or more blanks must follow RACROUTE. |
|
| |
|
| REQUEST=DIRAUTH |
|
| |
|
| ,RTOKEN=message token addr |
message token addr:
A-type address or register (2) – (12) |
| ,RESCSECLABEL=seclabel addr |
seclabel addr:
A-type address or register (2) – (12) |
| |
|
| ,ACCESS=READ |
Default=READ |
| ,ACCESS=READWRITE |
|
| ,ACCESS=WRITE |
|
| |
|
| ,ACEE=ACEE addr |
ACEE addr: A-type
address or register (2) – (12) |
| ,USERSECLABEL= |
seclabel addr:
A-type address or register (2) – (12) |
| seclabel addr |
|
| |
|
| ,ACEEALET=ALET addr |
ALET addr: A-type
address or register (2) – (12) |
| |
|
| ,CLASS=‘class name’ |
class name: 1–8
character name |
| ,CLASS=class name addr |
class name addr:
A-type address or register (2) – (12) |
| |
|
| ,LOG=ASIS |
Default=ASIS |
| ,LOG=NOFAIL |
|
| ,LOG=NONE |
|
| |
|
| ,LOGSTR=logstr addr |
logstr addr: A-type
address or register (2) – (12) |
| |
|
| ,TYPE=MAC |
Default=MAC |
| ,TYPE=EQUALMAC |
|
| ,TYPE=RVRSMAC |
|
| |
|
| ,MF=S |
|
|
The parameters are explained as follows: - ,ACCESS=READ
- ,ACCESS=READWRITE
- ,ACCESS=WRITE
- specifies the type of access attempt the user is requesting. This
value is used along with TYPE to determine how the user and resource
security labels are evaluated. If ACCESS is not specified, READ access
will be assumed. When specifying this parameter, RELEASE=7708 or later
must also be specified.
- ,ACEE=ACEE addr
- specifies the address of the user's ACEE. If specified, the security
label and write-down indicator from this ACEE will be used to determine
authorization. In cross-memory mode, the ACEE must be in the home
address space unless the ACEEALET= keyword specifies another address
space. If neither ACEE nor USERSECLABEL is specified, the ACEE of
the address space ( the home address space in cross memory mode)
will be used. When both ACEE and USERSECLABEL are specified, ACEE
is ignored. When specifying this parameter, RELEASE=7708 or later
must also be specified.
- ,ACEEALET=alet addr
- specifies the address of the 4-byte ALET to be used to access
the ACEE specified on the ACEE= keyword. If the ACEE= keyword is not
specified, the ACEEALET= keyword is ignored. When you use A-type or
RX-type notation, alet addr specifies the name
of a 4-byte field that contains the ALET. When you use register notation, alet
addr specifies a register that contains the address of a
4-byte field that contains the ALET. If this keyword is not specified,
the ACEE is located as defined in the ACEE= keyword description.
Keyword
requirements: - Run in supervisor state or system key (0–7).
- Ensure that the address space identified by ACEEALET= is marked
non-swappable.
- Ensure the specified ALET represents a valid entry in the DU-AL
of the work unit or the PASN-AL of the current primary address space.
- Specify RELEASE=7708 or later.
- ,CLASS=‘class name’
- ,CLASS=class name addr
- specifies a 1–8 character class name, or the address of an 8-byte
area containing the class name, left-justified and padded with blanks.
If a class name is specified and TYPE= is not specified, the CDT entry
of the class is used to determine the type of access check. When specifying
this parameter, RELEASE=7708 or later must also be specified.
- ,LOG=ASIS
- ,LOG=NOFAIL
- ,LOG=NONE
- specifies the type of access attempts that RACF® is to record on the SMF data
set. Failures that result in SMF recording will also produce an ICH408I
message unless MSGSUPP=YES is specified.
- ASIS
- RACF records the event
in the manner specified on the SETR LOGOPTIONS command for the DIRAUTH
resource class, unless a class name is specified. If a class name
is specified, the SETR LOGOPTIONS for that class will determine whether
or not auditing will occur.
- NOFAIL
- If the authorization check fails, RACF does
not record the attempt.
If the authorization check succeeds, RACF records the attempt as it
does in ASIS.
- NONE
- RACF does not record the
event or issue any messages.
- ,LOGSTR=logstr addr
- specifies the address of a 1-byte length field followed by character
data to be written to the system-management-facilities (SMF) data
set together with any RACF audit
information, if logged.
- ,RESCSECLABEL=seclabel addr
- specifies the address of an 8-byte area containing the security
label of a resource. Resources include server address spaces, network
resources, files, data sets, etc. The security label must be specified
in uppercase, left-justified, and padded with blanks. If RESCSECLABEL
is not specified, then RTOKEN must be specified. If both RESCSECLABEL
and RTOKEN are specified, RTOKEN is ignored. When specifying this
parameter, RELEASE=7708 or later must also be specified.
- ,RTOKEN=message token addr
- specifies the address of the token of a resource (RTOKEN). The
RTOKEN data contains the user token (UTOKEN) of the creator of the
resource. If the first two bytes (length and version) are equal to
0, it is the same as not specifying the RTOKEN. If RTOKEN is not specified,
RESCSECLABEL must be specified. If both RESCSECLABEL and RTOKEN are
specified, RTOKEN is ignored. When RTOKEN is specified with no additional
keywords except the optional LOG keyword, then the DIRAUTH class must
be active.
- ,TYPE=MAC
- ,TYPE=EQUALMAC
- ,TYPE=RVRSMAC
- specifies the type of dominance checking to be done for the security
labels specified: normal mandatory access (MAC) checking, equal MAC
checking and reverse MAC checking.If TYPE is not specified and CLASS
is specified, then CLASS name is used to determine the type of checking
to be done. If neither TYPE nor CLASS is specified, normal MAC checking
will be performed. When specifying this parameter, RELEASE=7708 or
later must also be specified.
The
type of dominance checking performed depends not only on the TYPE
value, but also the ACCESS value, the SETROPTS MLS or NOMLS setting,
and the user's write-down mode (as set by permission to the FACILITY
class profile IRR.WRITEDOWN.BYUSER). Table 1 describes
the security label dominance required for successful authorization
checking with each MAC type and ACCESS value. Table 1. Type of security label dominance required
for successful authorization checking with each MAC type and ACCESS
value| Values for the ACCESS parameter |
SETROPTS NOMLS in effect
or
the user in write-down mode
|
SETROPTS MLS in effect |
|---|
| |
TYPE=MAC |
| READ |
User dominance |
| READ/WRITE |
User dominance |
Equivalence |
| WRITE |
User or resource dominance |
Resource dominance |
| |
TYPE=EQUALMAC |
| READ |
Equivalence |
| READ/WRITE |
| WRITE |
| |
TYPE=RVRSMAC |
| READ |
Resource dominance |
| READ/WRITE |
Resource dominance |
Equivalence |
| WRITE |
User or resource dominance |
User dominance |
- ,USERSECLABEL=seclabel addr
- specifies the address of an 8-byte area containing the security
label of the user. The security label must be specified in uppercase,
left-justified, and padded with blanks. If neither USERSECLABEL nor
ACEE is specified, the ACEE of the address space will be used. If
both USERSECLABEL and ACEE are specified, ACEE is ignored. The write-down
privilege will be ignored if USERSECLABEL is used. When specifying
this parameter, RELEASE=7708 or later must also be specified.
The
dominance checking performed depends not only on the TYPE keyword,
but also the MAC keyword, the SETROPTS MLS/NOMLS setting, and whether
write-down mode is in effect (as set by permission to the facility
class profile IRR.WRITEDOWN.BYUSER). The above description applies
to TYPE=READ, for which the other factors have no affect. The following
table describes the dominance checking for all MAC specifications.
(Add table here.)
- ,MF=S
- specifies the standard form of the RACROUTE REQUEST=DIRAUTH macro
instruction.
Return codes and reason codes
When you execute the macro, space for the RACF return code and reason code is reserved
in the first two words of the RACROUTE parameter list. You can access
them using the ICHSAFP mapping macro, by loading the ICHSAFP pointer
with the label that you specified on the list form of the macro. When
control is returned, register 15 contains the SAF return code.
Note: All return and reason codes are shown in hexadecimal. Also, note that SAF return code is presented as SAF RC
and RACF return code is presented
as RACF RC in the following topic.
- SAF RC
- Meaning
- 00
- RACROUTE REQUEST=DIRAUTH has completed successfully.
- RACF RC
- Meaning
- 00
- Authorized to the resource
- Reason Code
- Meaning
- 00
- Function completed successfully.
- 04
- RTOKEN passed belongs to an operator or a trusted user. This code
is returned only if keywords are limited to RTOKEN and, optionally,
LOG.
- 04
- The requested function could not be performed.
- RACF RC
- Meaning
- 00
- No security decision could be made.
- Reason Code
- Meaning
- 00
- RACF was not called to
process the request because one of the following occurred:
- RACF is not installed.
- The combination of class, REQSTOR, and SUBSYS was found in the RACF router table, and ACTION=NONE
was specified.
- The RACROUTE issuer specified DECOUPL=YES and a RELEASE= keyword
with a higher release than is supported by this level of z/OS®.
- 04
- DIRAUTH cannot make a decision.
- Reason Code
- Meaning
- 00
- One of the following has occurred:
- ACEE does not contain TOKEN information.
- The DIRAUTH class or RACF is
not active. In this case, this return code is returned only when the
RTOKEN keyword is used without additional keywords (other than the
optional LOG keyword).
- 04
- Reserved.
- 08
- The definition of one of the provided security labels was not
found.
- 0C
- The translation of one of the security labels to its defining
security level and categories failed.
- 10
- The SECLABEL general-resource class was either not activated by
SETROPTS CLASSACT(SECLABEL) or not brought into storage by SETROPTS
RACLIST(SECLABEL).
- 14
- No defining security level exists in one of the SECLABEL profiles.
- 18
- Class not found and is needed to determine TYPE or LOGOPTIONS.
- 1C
- Could not access the RACLISTed dataspace for the SECLABEL class
due to an ALESERV failure.
- FF
- An unexpected error occurred while checking security-label authorization.
- 0C
- Parameters passed to DIRAUTH are not valid.
- Reason Code
- Meaning
- 00
- Either the resource token (RTOKEN) or security label (RESCSECLABEL)
was not specified.
- 04
- The resource token (RTOKEN) specified is not valid.
- 08
- Invoked in cross-memory mode but the calling program is not running
in supervisor state.
- 0C
- The ACEEALET= keyword was specified but the calling program is
not running in supervisor state or system key (0–7).
- 10
- Invoked in cross-memory mode but the RTOKEN keyword was used without
additional keywords (other than the optional LOG keyword).
- 08
- The requested function failed.
- RACF RC
- Meaning
- 08
- Not authorized to the resource. One of the following two cases
applies, depending on the keywords used:
- When the RTOKEN keyword is used without additional keywords (other
than the optional LOG keyword), the following reason codes apply:
- Reason Code
- Meaning
- 00
- The security label in the user's ACEE does not currently dominate
that of the RTOKEN. However, the user does possess a security label
that can dominate that of the RTOKEN.
- 04
- The security label in the user's ACEE does not dominate that of
the RTOKEN, and the user does not possess a security label that can
dominate that of the RTOKEN.
- When any additional keyword is used other than the RTOKEN keyword
alone, or RTOKEN with the optional LOG keyword, the following reason
code applies:
- Reason Code
- Meaning
- 00
- Not authorized to the resource.
- 64
- Indicates that the CHECK subparameter of the RELEASE keyword was
specified on the execute form of the RACROUTE REQUEST=DIRAUTH macro;
however, the list form of the macro does not have the same RELEASE
parameter. Macro processing terminates.
Example
Invoke the RACROUTE REQUEST=DIRAUTH macro on behalf of the VTAM® resource manager to perform
security-label authorization checking in the “receiving” user's address
space to ensure that the receiver's security label dominates that
of the message. Specify that RACF should
audit the event as specified in the SETROPTS LOGOPTIONS value for
the DIRAUTH class.
In this example, the receiver's security label can never dominate
the security label found in the TOKEN specified on the RTOKEN= keyword.
The return code received from the DIRAUTH service is 8 and the reason
code is 4. Note: The message cannot be received by anyone other than
the person to whom it was directed.
RACROUTE REQUEST=DIRAUTH,WORKA=RACWK,RTOKEN=(8), X
LOG=ASIS,RELEASE=1.9.2
⋮
RACWK DS CL512
|
z/OS Security Server RACROUTE Macro Reference
Copyright IBM Corporation 1990, 2014