|
The standard form of the RACROUTE REQUEST=VERIFY 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: - Application programs must be structured so that a task requesting RACF® services does not do so while
other I/O initiated by the task is outstanding. If such I/O is required,
the task should either wait for the other I/O to complete before requesting RACF services, or the other I/O
should be initiated under a separate task. This is necessary to assure
proper processing in recovery situations.
- 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=VERIFY |
|
|
|
,ACEE=address of |
address of fullword:
A-type address or register (2) – (12) |
fullword |
|
,ACTINFO=account addr |
account addr:
A-type address or register (2) – (12) |
|
|
,APPL=‘applname’ |
applname: 1–8
character name |
,APPL=applname addr |
applname addr:
A-type address or register (2) – (12) |
|
|
,ENCRYPT=YES |
Default: ENCRYPT=YES |
,ENCRYPT=NO |
|
|
|
,ENVIR=CREATE |
Default: ENVIR=CREATE |
,ENVIR=VERIFY |
|
,ENVIR=CHANGE |
|
,ENVIR=DELETE |
|
|
|
,ENVRIN=envr data addr |
envr data addr:
A-type address or register (2) – (12) |
|
|
,ENVROUT=envr data |
envr data addr:
A-type address or register (2) – (12) |
addr |
|
|
|
,ERROROPT=ABEND |
Default: ERROROPT=ABEND |
,ERROROPT=NOABEND |
|
|
|
,EXENODE=execution |
execution node addr:
A-type address or register (2) – (12) |
node addr |
|
|
|
,GROUP=group addr |
group addr: A-type
address or register (2) – (12) |
|
|
,ICRX=icrx addr |
icrx addr: A-type address
or register (2) – (12) |
|
|
,ICTX=ictx addr |
ictx addr: A-type address
or register (2) - (12) |
|
|
,IDID=idid addr |
idid addr: A-type address
or register (2) – (12) |
|
|
,INSTLN=parm list addr |
parm list addr:
A-type address or register (2) – (12) |
|
|
,JOBNAME=jobname |
jobname addr:
A-type address or register (2) – (12) |
addr |
|
|
|
,LOC=BELOW |
Default: See parameter description. |
,LOC=ANY |
|
|
|
,LOG=ASIS |
Default: LOG=ASIS |
,LOG=ALL |
|
,LOG=NONE |
|
|
|
,LOGSTR=logstr addr |
logstr addr: A-type
address or register (2) – (12) |
|
|
,NESTED=YES |
|
,NESTED=NO |
Default: NESTED=NO |
,NESTED=COPY |
|
|
|
,NEWPASS=new |
new password addr:
A-type address or register (2) – (12) |
password addr |
|
|
|
,NEWPHRASE=new |
new password phrase addr:
A-type address or register (2) – (12) |
password phrase addr |
|
|
|
,OIDCARD=oid addr |
oid addr: A-type
address or register (2) – (12) |
|
|
,PASSCHK=YES |
Default: PASSCHK=YES |
,PASSCHK=NO |
|
|
|
,PASSWRD=password |
password addr:
A-type address or register (2) – (12) |
addr |
|
|
|
,PGMNAME=programmer |
programmer name addr:
A-type address or register (2) – (12) |
name addr |
|
|
|
,PHRASE=password phrase |
password phrase addr: A-type
address or register (2)- (12) |
addr |
|
|
|
,POE=port of entry addr |
port of entry addr:
A-type address or register (2) – (12) |
,POENET=network name addr |
network name addr:
A-type address or register (2) – (12) |
|
|
,REMOTE=YES |
|
,REMOTE=NO |
Default: REMOTE=NO |
|
|
,SECLABL=seclabel addr |
seclabel addr:
A-type address or register (2) – (12) |
|
|
,SERVAUTH=servauth addr |
servauth addr:
A-type address or register (2) – (12) |
|
|
,SESSION=type |
type: Any valid
session type |
|
Default: SESSION=TSO |
|
|
,SGROUP=submitting |
submitting group addr:
A-type address or register (2) – (12) |
group addr |
|
|
|
,SMC=YES |
Default: SMC=YES |
,SMC=NO |
|
|
|
,SNODE=submitting node |
submitting node addr:
A-type address or register (2) – (12) |
addr |
|
|
|
,START=procname addr |
procname addr:
A-type address or register (2) – (12) |
|
|
,STAT=ASIS |
Default: STAT=ASIS |
,STAT=NO |
|
|
|
,STOKEN=stoken addr |
stoken addr: A-type
address or register (2) – (12) |
|
|
,SUBPOOL=subpool |
subpool number:
Decimal digit 0–255 |
number |
Default: See the description of the SUBPOOL keyword. |
|
|
,SUSERID=submitting |
submitting userid addr:
A-type address or register (2) – (12) |
userid addr |
|
|
|
,SYSTEM=NO |
Default: SYSTEM=NO |
,SYSTEM=YES |
|
Note: Use of the SYSTEM=
keyword requires that RELEASE=1.9.2 or later be specified. |
|
|
,TERMID=terminal addr |
terminal addr:
A-type address or register (2) – (12) |
|
|
,TOKNIN=utoken addr |
utoken addr: A-type
address or register (2) – (12) |
|
|
,TOKNOUT=utoken addr |
utoken addr: A-type
address or register (2) – (12) |
|
|
,TRUSTED=YES |
|
,TRUSTED=NO |
Default: TRUSTED=NO |
|
|
,USERID=userid addr |
userid addr: A-type
address or register (2) – (12) |
|
|
,X500NAME=X500 name |
name pair addr:
A-type address or register (2) – (12) |
pair addr |
|
|
|
,MF=S |
|
|
The parameters are explained as follows: - ,ACEE=address of fullword
- specifies the address of a fullword to be used as described below.
ENVIR=DELETE specifies
the address of a fullword that contains the address of the ACEE to
be deleted. If ACEE= is not specified or ACEE=0 is specified, and
the TCBSENV field for the task using the RACROUTE REQUEST=VERIFY is
nonzero, the ACEE pointed to by the TCBSENV is deleted, and TCBSENV
is set to zero. If the TCBSENV and ASXBSENV fields both point to the
same ACEE, ASXBSENV is also set to zero. If no ACEE address is passed,
and TCBSENV is zero, the ACEE pointed to by ASXBSENV is deleted, and
ASXBSENV is set to zero.
ENVIR=CHANGE specifies
the address of a fullword that contains the address of the ACEE to
be changed. if ACEE= is not specified, and the TCBSENV field for the
task using the RACROUTE REQUEST=VERIFY is nonzero, the ACEE pointed
to by the TCBSENV is changed. If TCBSENV is 0, the ACEE pointed to
by ASXBSENV is changed.
ENVIR=CREATE specifies
the address of a fullword in which the RACROUTE REQUEST=VERIFY function
places the address of the ACEE created.
The user should
not create an ACEE above 16MB and place the address in ASXBSENV or
TCBSENV. If an ACEE is not specified, the address of the newly created
ACEE is stored in the TCBSENV field of the task control block. If
the ASXBSENV field contains binary zeros, the new ACEE address is
also stored in the ASXBSENV field of the ASXB. If the ASXBSENV field
is nonzero, it is not modified. The TCBSENV field is set unconditionally
if ACEE= is not specified. Note: - If you omit USERID, GROUP, and PASSWRD and if you code ENVIR=CREATE
or if ENVIR=CREATE is used as the default, you receive a return code
of X'00' and obtain an ACEE that contains an asterisk (*)
(X'5C') in place of the USERID and group name.
- Specifying the ACEE= keyword prevents messages ICH70001I and ICH70002I
from being issued.
- When the ASXBSENV field is non-zero and only the new ACEE is being
anchored in TCBSENV, if the MLACTIVE option is on, the security label
associated with the address space must be equivalent to the security
label of the new ACEE.
- ,ACTINFO=account addr
- specifies the address of a field containing accounting information.
This 144-byte area is passed to the RACINIT installation exit routine;
it is not used by the RACROUTE REQUEST=VERIFY routine. The accounting
field, if supplied, should have the following format:
- The first byte of the field contains the number (in binary) of
accounting fields.
- The following bytes contain accounting fields, where each entry
for an accounting field contains a 1-byte length field, followed by
the data.
- ,APPL=‘applname’
- ,APPL=applname addr
- specifies the name of the application issuing the RACROUTE REQUEST=VERIFY
to verify the user's authority to access the application. This saves
the application from having to do a separate RACROUTE REQUEST=AUTH.
If
an address is specified, the address must point to an 8-byte application
name, left-justified, and padded with blanks if necessary.
- ,ENCRYPT=YES
- ,ENCRYPT=NO
- specifies whether RACROUTE REQUEST=VERIFY encodes the old password,
the new password, and the OIDCARD data passed to it.
The default
is YES. - YES
- Signifies that the data specified by the PASSWRD, NEWPASS, and
OIDCARD keywords are not pre-encoded. RACROUTE REQUEST=VERIFY encodes
the data before storing it in the user profile or using it to compare
against stored data.
- NO
- Signifies that the data specified by the PASSWRD, NEWPASS, and
OIDCARD keywords are already encoded. RACROUTE REQUEST=VERIFY bypasses
the encoding of this data before storing it in or comparing it against
the user profile.
Note: If the password was shipped from another system,
the encryption method must be the same on all systems using the password.
For example, the RACF password
authentication exit, ICHDEX01, must be identical on all systems.
Note: ENCRYPT=NO does not apply to PHRASE and
NEWPHRASE and is ignored if specified.
- ,ENVIR=CREATE
- ,ENVIR=VERIFY
- ,ENVIR=CHANGE
- ,ENVIR=DELETE
- specifies the action to be performed by the user initialization
component regarding the ACEE.
The default is CREATE. - CREATE
- The user should be verified and an ACEE created.
- VERIFY
- This call is not processed by RACF.
However, it can be processed by the SAF installation exit (ICHRTX00)
if wanted. If the installation does not satisfy this request in the
exit, the RACROUTE caller receives a return code of 4, with RACF return and reason codes of
zero. Other security products can choose to process this call. Refer
to your security product's documentation for details.
Note: Because a RACROUTE REQUEST=VERIFY,ENVIR=VERIFY can
be issued from a non-authorized state, the SAF installation exit,
in this case, runs in a non-authorized state. If the exit invokes
a service that requires the issuer to be in an authorized state, it
fails.
- CHANGE
- The ACEE should be modified according to other parameters specified
on RACROUTE REQUEST=VERIFY. You can change only the connect group
with this option.
- DELETE
- The ACEE should be deleted. This parameter should be used only
if a previous RACROUTE REQUEST=VERIFY has completed successfully.
Guideline: Issue a RACROUTE REQUEST=VERIFY,ENVIR=DELETE
to delete only an ACEE that you created. See Guidelines for changing or deleting an ACEE for
other options.
Restriction: ENVIR=CHANGE and ENVIR=DELETE cannot
be specified with the parameters as identified in the following table. Restricted parameters |
ENVIR=CHANGE |
ENVIR=DELETE |
---|
ACTINFO= |
X |
X |
APPL= |
X |
X |
ENVRIN= |
X |
X |
ENVROUT= |
X |
X |
ERROROPT= |
X |
X |
EXENODE= |
X |
X |
GROUP= |
|
X |
ICRX= |
X |
X |
ICTX= |
X |
X |
IDID= |
X |
X |
JOBNAME= |
X |
X |
NESTED= |
X |
X |
NEWPASS= |
X |
X |
NEWPHRASE= |
X |
X |
OIDCARD= |
X |
X |
PASSWRD= |
X |
X |
PGMNAME= |
X |
X |
PHRASE= |
X |
X |
POE= |
X |
X |
POENET= |
X |
X |
REMOTE= |
X |
X |
SECLABL= |
X |
X |
SERVAUTH= |
X |
X |
SESSION= |
X |
X |
SGROUP= |
X |
X |
SNODE= |
X |
X |
START= |
X |
X |
STOKEN= |
X |
X |
SUSERID= |
X |
X |
TERMID= |
X |
X |
TOKNIN= |
X |
X |
TRUSTED= |
X |
X |
USERID= |
X |
X |
X500NAME= |
X |
X |
- ,ENVRIN=envr data addr
- specifies the data structure that contains the information necessary
to re-create a security environment.
The address points to a data
structure defined in Table 1. The data
structure describes the storage location for the ENVR object. While
the format of the data structure pointed to by ENVRIN is known to
the RACROUTE invokers, the content of the object itself is known only
to the external security product.
Restrictions: This
keyword is recognized only when SYSTEM=YES and ENVIR=CREATE are also
specified. In addition, when ENVRIN is specified, only the following
keywords are recognized: - ACEE
- SUBPOOL
- LOC
- TOKNOUT
- TERMID
- POE
Most RACROUTE REQUEST=VERIFY parameters are not recognized
in ENVRIN processing because they do not affect the security environment
created. The security environment is created based upon the information
contained in the ENVR object. No security environment verification
(such as GROUP checking or APPL checking) is performed. The ACEE,
SUBPOOL, LOC, and TOKNOUT keywords are recognized as output parameters,
and are used to specify the location of the security environment and
to return information about the security environment. The ACEE that
results from expanding the ENVR object includes the X500 name, USP,
IDID, or ICTX if they exist.
The TERMID and POE keywords are
used to set/reset the terminal ID address field within the ACEE, ACEETRMP.
If the original request used to create the ENVR specified the TERMID
keyword, or the POE keyword with a session type of TSO, the ACEETRMP
field set is based upon the keyword information. Since the ENVR can
be used across address spaces or jobsteps, the issuer of the request
must determine whether the data pointed to by the ACEETRMP field when
the ENVR is processed is still valid.
The requester can use
the TERMID or POE keyword (or both) to modify the ACEETRMP field to
ensure its validity. If the TERMID keyword is specified on an ENVRIN
request, its address is placed in the ACEETRMP field. If the POE keyword
is specified on the ENVRIN request and the port of entry class associated
with the ENVR is the TERMINAL class, then its address is placed in
the ACEETRMP field (overriding the TERMID address if TERMID was also
specified). No class validation (such as checking the TERMID value
against the TERMINAL class) is performed against these keyword values
during ENVRIN processing.
- ,ENVROUT=envr data addr
- Specifies the data structure that is to hold the information that
is used to describe the security environment that was just created.
This
information can be used with the ENVRIN keyword to later re-create
the security environment without causing I/O to the RACF database. The address points to a data
structure defined in Table 1. The data
structure describes the storage location for the ENVR object. The
key of the ENVR data structure is a single-byte value that represents
the associated ENVR object storage area. The low-order nibble of this
value is the storage key. A key value of X'07' returns an ENVR object
in key 07 storage.
While the format of the data structure pointed
to by ENVROUT is known to the RACROUTE invokers, the content of the
object itself is determined by the external security product.
Restriction: This
keyword is only recognized when SYSTEM=YES and ENVIR=CREATE are also
specified.
Figure 1 and Table 1 represent the ENVR data structure for
use with the ENVRIN and ENVROUT keywords. The data structure must
start on a fullword boundary.
Figure 1. ENVR data structure
Table 1. Description of ENVR data
structureDescription |
Length (bytes) |
ENVROUT usage |
ENVRIN usage |
---|
ENVR object length |
4 |
Output |
Input |
ENVR object storage area length |
4 |
Input/output |
Input |
ENVR object storage area address |
4 |
Input/output |
Input |
ENVR object storage area subpool |
1 |
Input |
N/A |
ENVR object storage area key |
1 |
Input |
N/A |
The ENVR object storage area can be supplied by the caller
or obtained by RACF. If supplied
by the caller, it must be on a doubleword boundary and be associated
with the job step task. If RACF obtains
the storage area, it is on a doubleword boundary and is associated
with the jobstep task. The storage is allocated based on the mode
of the caller (LOC=ANY for 31-bit callers and LOC=BELOW for 24-bit
callers). The following table shows how the field values affect ENVROUT
processing.
Table 2. ENVROUT storage area processingENVR object storage area length |
ENVR object storage area address |
Result |
---|
Zero |
Any value |
RACF obtains minimum
storage size needed to contain the ENVR object. Storage size is returned
in the ENVR object storage area length. Storage address is returned
in the ENVR object storage area address. |
Nonzero |
Zero |
RACF obtains storage
size specified or the minimum storage size needed to contain the ENVR
object. Storage size is returned in the ENVR object storage area length.
Storage address is returned in the ENVR object storage area address. |
Nonzero |
Nonzero |
RACF attempts to use
the storage area provided. If the area is too small to contain the
ENVR object, RACF frees the
storage area provided and obtains the minimum storage size needed
to contain the ENVR object. Storage size is returned in the ENVR object
storage area length. Storage address is returned in the ENVR object
storage area address. |
Storage is obtained and freed in the subpool and key specified
in the ENVR data structure. Since the ENVR object length is returned
to the caller, the ENVR object can be moved from one storage area
to another. This value is supplied as an output to the caller. RACF does not attempt to use this
value in either ENVROUT or ENVRIN processing.
The caller is
responsible for freeing the ENVR object storage area when it is no
longer needed. The length, address, subpool, and key to be used when
doing the FREEMAIN are contained in the ENVR data structure.
The
ENVR object returned by ENVROUT= is a relocatable object that can
be copied from one storage location to another. The returned ENVR
object, or a copy of the returned ENVR object, can be specified as
input to the RACROUTE interface using the ENVRIN keyword, or to the
initACEE callable service using the ENVR_in parameter.
The ENVR
object can be passed to other systems, but this should be done with
great care. The ENVR object should not be saved for a long time before
being used as ENVRIN, and it should not be passed to systems that
have different security information. The other systems should share
the RACF database and have
compatible RACF installation
exits and class descriptor tables.
- ,ERROROPT=ABEND
- ,ERROROPT=NOABEND
specifies whether RACROUTE REQUEST=VERIFY will abend or not
when an error occurs while it is accessing the RACF database.
The default is ABEND.
- ABEND
- When RACROUTE REQUEST=VERIFY encounters an error accessing the RACF database, issue a 483 abend.
- NOABEND
- When RACROUTE REQUEST=VERIFY encounters an error accessing the RACF database, 483 abends are suppressed.
Instead, the request receives a SAF RC 8, RACF RC X'5C' and a RACF reason code of X'0483yyyy' where
'yyyy' is the RACF manager
return code associated with the abend that would have been issued.
If you are specifying the ERROROPT keyword with a specific release
value, RELEASE=value, Table 3 shows
how RELEASE= values affect the operation of the ERROROPT keyword:
Table 3. Relationship between the ERROROPT
keyword and RELEASE= valuesRelease |
Action |
---|
All earlier releases |
ERROROPT keyword is flagged as an unknown keyword. |
7703 and 7705 |
ERROROPT keyword is syntax checked only and
an informational MNOTE indicating that the ERROROPT keyword is being
ignored is returned. No abend suppression is performed. However, the
SAF parameter list is built with the ERROROPT bit set. This allows
programs which are assembled with RELEASE=7703 and RELEASE=7705 to
take advantage of ERROROPT=NOABEND once the applications are executed
in a z/OS Version 1 Release 3 (HBB7706)
or later environment. |
7706 and later |
483 abends are replaced with a SAF return code
of 8, a RACF return code of X'5C',
and a RACF reason code of X'0483yyyy'.
"yyyy" is the RACF manager
return code associated with the abend that would have been issued. |
- ,EXENODE=execution node addr
- specifies the address of an area that contains a 1-byte length
field followed by the name of the node on which the unit of work is
to be executed. The node name cannot exceed eight bytes.
- ,GROUP=group addr
- specifies the group specified by the user who has entered the
system. The address points to a 1-byte length field, followed by the
group name, which can be up to eight characters. When the GROUP= keyword
is omitted, if a user ID is specified, it defaults to the user's default
group; if the user ID is allowed to default to "*", then the
group will also default to "*".
Applications should fold the
group name to uppercase.
- ,ICRX=icrx addr
- specifies an address that points to a caller-provided ICRX area.
See the IRRPICRX mapping in z/OS Security Server RACF Data Areas.
The
ICRX might contain an identity context reference (ICR). When an ICRX
with an ICR is specified on a RACROUTE REQUEST=VERIFY, ENVIR=CREATE
request, VERIFY uses it to determine the appropriate RACF user ID. In this case, all keywords except
the following are ignored:
RACF attempts
to resolve the ICR from the local identity context cache using the
R_cacheserv callable service. RACF continues
according to one of the following cases:
Note: R_cacheserv attempts to resolve the ICR using the local
identity context cache and also other relevant identity context caches
that it can reach through RACF sysplex
communication. Only ICRs that are created by an R_cacheserv store
function are supported. See z/OS Security Server RACF System Programmer's Guide for
more information.
If the ICRX does not contain an ICR, and
the IDIDMAP class is active, and the RACLIST macro has been issued,
RACROUTE REQUEST=VERIFY processing attempts to map to a RACF user ID using the distributed identity
information in the IDID and mapping filters previously defined using
the RACMAP command.
During the mapping process the following
operations are performed on a copy of the data (the original data
are not modified): - All leading and trailing blanks (x'20'), nulls (x'00'), or combination
of blanks and null characters are removed from the distributed identity
information strings in the IDID, and the lengths are appropriately
adjusted.
- If the distributed-identity-user-name (user name) is in X.500
format the name is normalized before it is used to find the matching RACF user ID that is associated
with the distributed identity filter.
The normalization rules are described in detail under RACMAP
MAP.
If the information in the IDID does not map to a RACF user ID, the RACROUTE REQUEST=VERIFY
fails and returns "user not defined".
If a RACF user ID is determined, RACROUTE REQUEST=VERIFY
processing continues with this user ID, and PASSCHK=NO is assumed.
All other supplied parameters are used. If an ACEE is successfully
created, the ACEE points to a copy of the IDID information from the
ICRX, and it is used in auditing.
Unless the ICRX was previously
obtained from R_cacheserv, the caller must set the ICRX ID, version,
subpool, length, and all applicable field length and offset values. RACF validates the id and checks
that the specified length values in the RACF sections
do not exceed allowed maximum values. Note: The caller must free the
ICRX structure.
The ICRX parameter is valid only for
the ENVIR=CREATE function of a REQUEST=VERIFY request. The ENVIR=CREATE
function ignores the ICRX parameter if both the ENVRIN parameter and
SYSTEM=YES parameter are specified.
The ICRX parameter is not
valid when specified with any of the following parameters: - IDID
- ICTX
- NESTED=YES
- NESTED=COPY
When specifying ICRX=, you must specify RELEASE=7760 or
later.
- ,ICTX=ictx addr
- specifies an address that points to a caller-provided ICTX area.
See the IRRPICTX mapping in z/OS Security Server RACF Data Areas.
The
caller must obtain storage for the ICTX above the 16 megabyte line
in the ACEE subpool specified by the issuer of RACROUTE REQUEST=VERIFY,
or in subpool 255 if an ACEE subpool is not specified. The ICTX area
must be on a doubleword boundary and must be associated with the job
step task.
The identity context information in the ICTX area
is used by RACF when it writes
SMF audit records for this user.
The caller is responsible for
setting the ICTX id, version, subpool, length, and all applicable
field length and offset values. RACF checks
the id and version; verifies that the ICTX subpool is the same as
the ACEE subpool; validates that the specified length values do not
exceed allowed maximum values; then sets ACEEICTX to the address of
the caller-provided area. On an unsuccessful return code, the caller
is responsible for freeing the input ICTX block. On a successful return
code, if the block is used, it is anchored in the ACEE and RACF frees it when the ACEE is
deleted. If ICTX= is specified but not used (that is, an ICTX was
resolved from an identity context reference), RACF frees the input ICTX block.
The ICTX
parameter applies to any SESSION type, but only for ENVIR=CREATE.
If it is specified along with an identity context reference (USERID
and PASSWRD parameters) that is successfully resolved, RACF builds the ICTX and the caller-provided
ICTX area will not be used. When specifying ICTX=, you must also specify
RELEASE=7730 or later.
- ,IDID=idid addr
- specifies an address that points to a caller-provided IDID area.
See the IRRPIDID mapping in z/OS Security Server RACF Data Areas.
The
caller must obtain storage for the IDID above the 16 megabyte line
in the ACEE subpool specified by the issuer of RACROUTE REQUEST=VERIFY,
or in subpool 255 if an ACEE subpool is not specified.
The IDID
area must be on a doubleword boundary and must be associated with
the job step task.
The distributed identity information in the
IDID area is used by RACF when
it writes SMF audit records for this user.
The caller must define
the IDID identifier, version, subpool, length, and all applicable
field length and offset values. RACF verifies
that the IDID subpool is the same as the ACEE subpool, validates the
ID, and checks that the specified length values in the RACF sections do not exceed allowed maximum
values. RACF then sets ACEEIDID
to be the address of the caller-provided area. If RACROUTE REQUEST=VERIFY
is not successful, the caller must free the input IDID block. If RACROUTE
REQUEST=VERIFY is successful, the caller's IDID is anchored in the
ACEE, and RACF frees it when
the ACEE is deleted.
The IDID parameter is valid only for the
ENVIR=CREATE function of a REQUEST=VERIFY request. The ENVIR=CREATE
function ignores the parameter in the following circumstances:
The IDID parameter is not valid when specified with any
of the following parameters: - ICRX
- ICTX
- NESTED=YES
- NESTED=COPY
When specifying IDID=, you must specify RELEASE=7760 or
later.
- ,INSTLN=parm list addr
- specifies the address of an area containing parameter information
meaningful to the RACINIT installation exit routine. This area is
passed to the installation exit when the exit routine is given control
from the RACROUTE REQUEST=VERIFY routine.
The INSTLN parameter
can be used by an installation having a user-verification or job-initiation
application, and wanting to pass information from one installation
module to the RACINIT installation exit routine.
- ,JOBNAME=jobname addr
- specifies the address of the job name of a background job. The
address points to an 8-byte area containing the job name (left-justified
and padded with blanks if necessary). The JOBNAME parameter is used
during authorization checking to verify the user's authority to submit
the job. It is passed to the installation exit routine. Also, if JOBNAME=
is specified with the START= parameter, and the STARTED class is active, RACF uses the jobname during its
processing to help determine the user ID and group name that are assigned
for the started task.
- ,LOC=BELOW
- ,LOC=ANY
- specifies whether the ACEE and related data areas are to be allocated
storage below 16MB (LOC=BELOW), or anywhere (LOC=ANY).
If the ACEE=
parameter is not coded, or if the caller is executing in 24-bit mode,
LOC=BELOW is the default and LOC=ANY is ignored if specified. In all
other cases, the default is LOC=ANY.
- ,LOG=ASIS
- ,LOG=ALL
- ,LOG=NONE
- specifies when log records are to be generated.
The default
is ASIS. - ASIS
- Only those requests to create an ACEE that fail generate RACF log records.
- ALL
- A request to create an ACEE, regardless of whether it succeeds
or fails, generates a RACF log
record. This applies when either ENVIR=CREATE or ENVIR=DELETE is specified.
- NONE
- A request to create an ACEE, regardless of whether it succeeds
or fails, does not generate a RACF log
record. This applies when either ENVIR=CREATE or ENVIR=DELETE is specified.
LOG=NONE
suppresses both messages and SMF records regardless of MSGSUPP=NO.
Note: SMF records are written for password changes
when SETROPTS AUDIT(USER) is in effect regardless of the LOG setting
specified.
- ,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.
- ,NESTED=YES
- ,NESTED=NO
- ,NESTED=COPY
- specifies whether the created ACEE should contain an ENVR object
for the current ACEE of the address space, a copy of the nested ENVR
object, or neither. The nested security environment can be used in
a subsequent RACROUTE REQUEST=FASTAUTH to grant access to a delegated
resource (a resource defined with the 'RACF-DELEGATED' string in the
APPLDATA field) when the client is not specifically permitted to it,
but the daemon is authorized. The default is NESTED=NO.
Rule: When
specifying NESTED=, you must also specify RELEASE=7720 or later.
- YES
- Specifies that the created ACEE should contain an ENVR object
for the ACEE for the current address space, if one exists. The ACEE
is created as specified by the other keywords in the request but the
ACEE information for the current address space is nested, or
encapsulated, within the created ACEE to preserve the current security
environment. Preserving the current security environment for a server
or daemon address space is useful when a security environment is created
for a new client.
- NO
- Specifies that the created ACEE should not contain a nested ENVR
object for the ACEE for the current address space.
- COPY
- Specifies that the created ACEE should contain a copy of the ENVR
object nested within the ACEE of the current address space, if a nested
ACEE exists for the address space. That is, the same security environment
that is nested for the address space should also be nested within
the newly created ACEE. Server and daemon applications that allow
the client to switch identities can use this option to preserve the
identity of the server or daemon while building a security environment
for a new client identity.
- ,NEWPASS=new password addr
- specifies the password that is to replace the user's currently
defined password. The address points to a 1-byte length field, followed
by the password, which can be up to eight characters.
The NEWPASS=
keyword has no effect unless PASSCHK=YES is either defaulted to or
explicitly specified and PASSWRD= is also specified. If the NEWPASS=
keyword is specified with PASSCHK=NO, no error message is issued but
the password is not changed. A new password phrase cannot be set using
a password for authentication, nor can a new password be set using
a password phrase for authentication.
- ,NEWPHRASE=new password phrase addr
- specifies the password phrase that is to replace the user's currently
defined password phrase. The address points to a 1-byte length field,
followed by the password phrase, which can be 14-100 characters (or
9-100 characters if the new password phrase exit, ICHPWX11, is installed
and accepts the new value). Specifying a length field of zero is equivalent
to not specifying NEWPHRASE.
RACF checks
the following set of basic rules for the value specified by NEWPHRASE:
- The user ID is not part of the password phrase.
- At least two alphabetics are specified (A - Z, a - z).
- At least two non-alphabetics are specified (numerics, punctuation,
special characters, blanks).
- No more than two consecutive characters are identical.
If NEWPHRASE is specified without PHRASE, it is not used unless
the user already has a password phrase, and PASSWRD is specified with
a PassTicket instead of a password. If PASSWRD is specified with a
PassTicket, and both NEWPASS and NEWPHRASE are specified, NEWPHRASE
is used. A new password phrase cannot be set using a password for
authentication, nor can a new password be set using a password phrase
for authentication.
If NEWPHRASE is specified with PASSCHK=NO,
no error message will be issued but the password phrase will not be
changed.
When specifying NEWPHRASE=, you must also specify RELEASE=7730
or later.
- ,OIDCARD=oid addr
- specifies the address of the currently defined operator-identification
card of the user who has entered the system. The address points to
a 1-byte length field, followed by the operator ID card.
- ,PASSCHK=YES
- ,PASSCHK=NO
- specifies whether the user's password, password phrase or OIDCARD
is to be verified.
- YES
- RACROUTE REQUEST=VERIFY verifies the user's password, password
phrase or OIDCARD.
There are some circumstances where verification
does not occur even though PASSCHK=YES is specified. Some examples
are surrogate processing (see z/OS Security Server RACF Security Administrator's Guide)
or when the START or the ENVRIN keywords are specified.
- NO
- The user's password, password phrase, or OIDCARD is not verified.
And, if the logon is successful, no message is issued.
- ,PASSWRD=password addr
- specifies the currently defined password of the user who has entered
the system. The address points to either:
- a 1-byte length field, followed by the password, which can be
up to eight characters, or
- a 1-byte length field, followed by a PassTicket, which is always
eight bytes.
Note: The currently defined password is maintained in the case
entered, except when the following occurs: if the PASSASIS bit is
off in the user's profile and the password does not match the current
password in the user's profile, the password is folded to uppercase
and again compared to the current password provided MIXEDCASE PASSWORD
support is enabled in SETROPTS.
- ,PGMNAME=programmer name addr
- specifies the address of the name of the user who has entered
the system. This 20-byte area is passed to the RACINIT installation
exit routine; it is not used by the RACROUTE REQUEST=VERIFY routine.
- ,PHRASE=password phrase addr
- specifies the currently defined password phrase of the user who
has entered the system. The address points to a 1-byte length field,
followed by the password phrase, which can be 9-100 characters. Specifying
a length field of zero is equivalent to not specifying PHRASE.
The
PASSWRD and OIDCARD parameters will be not be used if the PHRASE parameter
is specified.
Password phrases will not be checked in cases
where a password is not checked (PASSCHK=NO, START= or ENVRIN= specified,
SURROGAT processing).
When specifying PHRASE=, you must also
specify RELEASE=7730 or later.
- ,POE=port of entry addr
- specifies the address of the port of entry into the system. The
address points to the name of the input device through which the user
or job entered the system. For example, this could be the name of
the input device through which the job was submitted or the terminal
logged on to. The port of entry is an 8-character field that is left-justified
and padded with blanks.
The port of entry becomes a part of the
user's security token (UTOKEN). A flag in the UTOKEN uniquely identifies
the RACF general-resource class
to which the data in the POE field belongs: APPCPORT, TERMINAL, CONSOLE,
or JESINPUT. The SERVAUTH class can also be a port of entry but it
must be specified using the SERVAUTH keyword.
The RACF class, JESINPUT, provides the conditional
access support for jobs entered into the system through a JES input
device, and the CONSOLE class performs the same task for commands
that originate from a console. The APPCPORT class provides conditional
access support for users entering the system from a given LU (APPC
port of entry).
If the JESINPUT class is active and the JESINPUT
profile protecting this port of entry has a security label other than
SYSMULTI, it will override the user's default security label if the
SECLABEL keyword is not specified and the RACF option SECLBYSYSTEM is active on the system.
The
TERMINAL class covers the terminal used to log on to TSO.
When
both the POE and TERMID keywords, or both the POE and SERVAUTH keywords,
are specified the POE keyword takes precedence. Information specified
by POE= on an ENVIR=CREATE can be attached to the created ACEE and
used in subsequent RACF processing. RACF does not make its own copy
of this area when attaching this information to the created ACEE.
This area must not be explicitly freed before the deletion of the
ACEE. For the same reason, the area must reside in a non-task-related
storage subpool so that implicit freeing of the area does not occur.
Restriction: The
POE keyword does not allow the length needed for a SERVAUTH resource
representing an IP address.
- ,POENET=network name address
- specifies the address of a structure that consists of a 1-byte
length field followed by up to an 8-byte field containing the network
name of the partner LU. When specified with the POE parameter, the
value specified for POENET is combined with the value specified for
POE to create a network qualified name in the form netid.luname.
The network qualified LU name is then used as the POE value during
further processing. POENET is only valid with SESSION=APPCTP, and
should not be specified with any other type of session. To specify
the POENET parameter, you must specify RELEASE=2.6.
- ,REMOTE=YES
- ,REMOTE=NO
- specifies whether the job came through the network. The default
is REMOTE=NO.
- ,SECLABL=seclabel addr
- specifies the address of an 8-byte, left-justified character field
containing the security label, padded to the right with blanks.
To
use this keyword, you must specify RELEASE=1.9 or a later release
number.
If you do not specify the SECLABEL parameter while the
SECLABEL class is active, a security label may be derived from other
parameters in the following order: - TOKNIN=
- SERVAUTH=
- TERMID=
- JESINPUT (if SECLBYSYSTEM is active and the security label is
other than SYSMULTI)
- Default security label from user profile
If a security label was not found in any of these places, the
user is assigned a security label of SYSLOW only when both of the
following conditions are true: - MLACTIVE is in effect.
- The user is authorized to the SYSLOW SECLABEL profile.
An installation can use security labels to establish an
association between a specific RACF security
level (SECLEVEL) and a set of (zero or more) RACF security categories (CATEGORY). If it is
necessary to use security labels to prevent the unauthorized movement
of data from one level to another when multiple levels of data are
in use on the system at the same time, see z/OS Security Server RACF Security Administrator's Guide for
further information.
- ,SERVAUTH=servauth addr
- specifies the address of the identifier for the server through
which the user is accessing the system. The address points to a 1-byte
length field followed by up to a 64-byte area containing the name
of a resource in the SERVAUTH class. This resource is the network
access security zone name that contains the IP address of the user.
If the SERVAUTH class is active and the SERVAUTH profile protecting
this resource has a security label other than SYSMULTI, it will override
the user's default security label if the SECLABEL keyword is not specified.
After verifying that the user has access to this resource, a copy
of the information specified by SERVAUTH= on an ENVIR=CREATE is attached
to the created ACEE and used in subsequent RACF processing. If the POE keyword is specified,
the SERVAUTH keyword is ignored. When the SERVAUTH keyword is specified,
POE information in the STOKEN or TOKNIN and the TERMID keyword are
ignored. When specifying SERVAUTH=, you must also specify RELEASE=7708
or later.
Rule: When both the POE and SERVAUTH parameters
are specified, SERVAUTH is ignored.
- ,SESSION=type
- specifies the session type to be associated with the request.
Session types are literals. When the SESSION keyword is used in combination
with the POE keyword, SESSION determines the class with which the
POE keyword is connected.
When the session type is APPCTP, RACF requires APPL= and POE= also
to be specified. The APPL= value should be the address of the local
LU name, and the POE= value should be the address of the remote LU
name.
If SERVAUTH is specified, the default session
type is IP. If SERVAUTH is not specified and TERMID= or POE= is specified,
the default session type is TSO. Otherwise, session type is not set.
Restrictions
for the IP session type: - If a session type of IP is specified with the POE keyword, a parameter
list abend will occur.
- As with the OMVSSRV session type, the last access date and time
messages are not issued.
The allowable session types and their associated POE
classes are: Session type |
Description |
POE class |
---|
APPCTP |
An APPC transaction program. When APPCTP is specified, user
profile statistics are updated daily at most.
|
APPCPORT |
COMMAND |
A command |
CONSOLE |
CONSOPER |
A console operator |
CONSOLE |
EXTBATCH |
A job from external reader (EXT) |
JESINPUT |
EXTXBM |
An execution batch monitor job |
JESINPUT |
INTBATCH |
A batch job from internal reader (INT) |
JESINPUT |
INTXBM |
An execution batch monitor job from INT |
JESINPUT |
IP |
A TCP/IP address |
None |
MOUNT |
A mount |
None |
NJEBATCH |
A job from network job entry (NJE) |
JESINPUT |
NJEOPER |
A network job entry operator |
JESINPUT |
NJEXBM |
A network execution batch monitor job |
JESINPUT |
NJSYSOUT |
A network SYSOUT |
JESINPUT |
OMVSSRV |
An OMVS server application When OMVSSRV is specified, user
profile statistics are updated daily at most. Audit records are only
created when one of the following conditions are met: - An incorrect password or password phrase is specified.
- The user ID has been revoked.
- A new password or password phrase was provided.
- A SECLABEL error occurred.
|
None |
RJEBATCH |
A batch job from remote job entry (RJE) |
JESINPUT |
RJEOPER |
A remote job-entry operator |
JESINPUT |
RJEXBM |
A remote execution batch monitor job |
JESINPUT |
STARTED |
A started procedure of started task |
None |
SYSAS |
A system address space |
None |
TKNUNKWN |
An unknown user from NJE |
JESINPUT |
TSO |
A TSO or other interactive session logon |
TERMINAL |
Note: When there is no POE class associated with the session
type, the POE ID and session are preserved.
- ,SGROUP=submitting group addr
- specifies the address of an area that contains a 1-byte length
field followed by the group name of the user who submitted the unit
of work. The group ID cannot exceed eight bytes.
- ,SMC=YES
- ,SMC=NO
- specifies the use of the step-must-complete function of RACROUTE
REQUEST=VERIFY processing.
- YES
- RACROUTE REQUEST=VERIFY processing makes other tasks for the job
step non-dispatchable.
- NO
- The step-must-complete function is not used.
Note: - SMC=NO should not be used if DADSM ALLOCATE/SCRATCH functions
execute simultaneously in the same address space as the RACROUTE REQUEST=VERIFY
function.
- When an automatic direction of application updates RACROUTE REQUEST=VERIFY
request is issued with the SMC keyword specified, the SMC keyword
is not propagated.
- ,SNODE=submitting node addr
- specifies the address of an area that contains a 1-byte length
field followed by the name of the node from which the unit of work
was submitted. The node name cannot exceed eight bytes.
- ,START=procname addr
- specifies the procedure name of the started task for which the
RACROUTE REQUEST=VERIFY is being performed. The address points to
an 8-byte area containing the procedure name (left-justified and padded
with blanks, if necessary). If START= is specified, REQUEST=VERIFY
processing searches the started procedure table for the user ID and
group to use for this REQUEST=VERIFY request. If the USERID and GROUP
keywords are specified, REQUEST=VERIFY uses those values if it cannot
find a STARTED class profile or an entry in the started procedure
table that matches the specified procedure name (and jobname from
JOBNAME= if the STARTED class is used.)
If START is specified,
PASSWRD and OIDCARD should not be specified.
- ,STAT=ASIS
- ,STAT=NO
- specifies whether the statistics controlled by the options specified
on the RACF SETROPTS command
should be maintained or ignored for this execution of RACROUTE REQUEST=VERIFY.
This parameter also controls whether a message is to be issued when
the logon is successful.
The default is ASIS. Note: Messages are
always issued if the RACROUTE REQUEST=VERIFY processing is unsuccessful.
- ASIS
- The messages and statistics are controlled by the installation's
current options on the RACF SETROPTS
command.
Note: - If SESSION=OMVSSRV or SESSION=APPCTP is specified, RACF updates the date and time of the user access
at most once per day overriding the STAT=ASIS keyword.
- For applications that specify the APPL operand, by specifying
the RACF-INITSTATS(DAILY) string in the APPLDATA field, administrators
can use the APPL class profiles, which are used to control which users
can access the application, to specify which applications are to only
have daily user statistics recorded. For more information, see the z/OS Security Server RACF Security Administrator's Guide.
- NO
- The statistics are not updated. And, if the logon is successful,
no message is issued.
When STAT=NO is specified, the request does
not result in the user being revoked even if the user's statistics
have not been updated within k days, where k is
the inactive period defined using SETROPTS INACTIVE(k).
- ,STOKEN=stoken addr
- specifies the address of the submitter's UTOKEN. The first byte
contains the length of the UTOKEN, and the second byte contains the
format version number. See ICHRUTKN mapping, "RUTKN: Resource/User
Security Token" in z/OS Security Server RACF Data Areas.
If
you specify an STOKEN, the USERID in the STOKEN becomes the submitter's
ID in the ACEE's token unless you specified the submitter's ID (SUSER)
keyword. If you did, that keyword becomes the submitter's ID in the
ACEE's token. Likewise, if you specified GROUP in STOKEN, that becomes
the submitter's group in the ACEE's token, unless you specified the
submitter's group (SGROUP) keyword. The SESSION, port-of-entry (POE),
and port-of-entry class (POEX) fields are also used from the STOKEN.
The execution node becomes the resulting submit node and execution
node, unless you specify the submit node (SNODE) or execution-node
address (EXENODE) keywords. In all cases, the specified keywords on
the request override the fields of the STOKEN, if one is specified.
Also,
STOKEN is used for surrogate checking, security-label dominance, or
JESJOBS checking unless different submitter-checking information is
supplied.
- ,SUBPOOL=subpool number
- specifies the storage subpool from which the ACEE and related
storage are obtained. The value of the subpool can be literally specified
or passed through a register. When using a register, the subpool number
is the value of the least significant byte in the register.
If
this parameter is not specified, it defaults to 255. Note: - Take care in selecting a subpool, as MVS™ makes
certain assumptions about subpool usage and characteristics. In particular,
using subpool 0 or 250, or any subpool documented in z/OS MVS Programming: Assembler Services Guide as
having a storage key of USER (for example, 227-231, and 241) can give
unpredictable results.
In
choosing a subpool, be aware that the storage obtained can be attached
to MVS control blocks, so subpool
characteristics need to be considered. Suppose, for example, that
a task-related subpool is chosen for the ACEE; if you do not provide
an anchor for the ACEE, in some cases the ACEE is attached to the MVS ASXB. When the task terminates,
the ACEE storage is freed and the ASXB points to freemained storage.
If
a task related subpool is chosen, the application must ensure that
only the task that created the ACEE is allowed to use it. Similarly,
if a job step related subpool is chosen, only tasks that are associated
with the same job step TCB as the task that created the ACEE may use
that ACEE. Allowing other tasks (such as system or initiator tasks)
to use it may cause unpredictable ABENDs.
- If a common-area subpool (for example 226–228, 231, 239, 241,
245, 247, or 248) is used and not freed before the job terminates,
then the job might show up in the exception reports of RMF™ (or other monitoring tools that support the
tracking of common-area storage utilization) as owning common storage.
Before your job terminates, it should issue a RACROUTE REQUEST=VERIFY,
ENVIR=DELETE to free this common storage.
- ,SUSERID=submitting userid addr
- specifies the address of an area that contains a 1-byte length
field, followed by the user ID of the user who submitted the unit
of work. The user ID cannot exceed eight bytes.
Applications should
fold the submitting user ID to uppercase.
- ,SYSTEM=NO
- ,SYSTEM=YES
- specifies whether the caller is in supervisor state or system
key 0–7, or both.
- NO
- indicates that the caller cannot guarantee to be in supervisor
state or system key 0–7.
- YES
- indicates that the caller is in supervisor state and/or system
key 0–7.
SYSTEM=YES is used to provide a fast path through
RACROUTE REQUEST=VERIFY. However, unless ENVRIN is also specified,
using any of the following keywords nullify the benefits of the fastpath: EXENODE NESTED OIDCARD SGGROUP STOKEN TOKNIN
JOBNAME NEWPASS REMOTE SNODE SUSERID NEWPHRASE
When
ENVRIN is specified, the indicated keywords are ignored, therefore
the “fastpath” benefit is recognized.
The default is SYSTEM=NO. Note: - If the caller specifies SYSTEM=YES and is in neither supervisor
state nor system key 0–7, the request abends.
- Use of the SYSTEM=keyword requires that RELEASE=1.9.2 or later
be specified.
- ,TERMID=terminal addr
- specifies the address of the identifier for the terminal through
which the user is accessing the system. The address points to an 8-byte
area containing the terminal identifier. Information specified by
TERMID= on an ENVIR=CREATE can be attached to the created ACEE and
used in subsequent RACF processing. RACF does not make its own copy
of this area when attaching this information to the created ACEE.
This area must not be explicitly freed before the deletion of the
ACEE. For the same reason, the area must reside in a non-task-related
storage subpool so that implicit freeing of the area does not occur.
If POE= is specified, the TERMID= area is not referred to in subsequent
processing and can be freed at the user's discretion.
If the TERMINAL
class is active and the TERMINAL profile protecting this resource
has a security label other than SYSMULTI, it will override the user's
default security label if the SECLABEL keyword is not specified.
Rule: When
both the TERMID and SERVAUTH keywords are specified, the SERVAUTH
keyword takes precedence.
- ,TOKNOUT=utoken addr
- specifies an address that points to a user-provided area in which
the UTOKEN is built. The mapping of the area is a 1-byte length field,
followed by a 1-byte version code, followed by a 78-byte area in which
to build the UTOKEN. This token is extracted from the ACEE built by
this request.
- ,TOKNIN=utoken addr
- specifies an address that points to a caller-provided area that
contains an input UTOKEN. The mapping of the area is a 1-byte length
field, followed by a 1-byte version code, followed by the UTOKEN itself,
which can be 78 bytes long. The TOKNIN should have been previously
obtained by RACROUTE REQUEST=VERIFY, VERIFYX, TOKENXTR or TOKENBLD.
- ,TRUSTED=YES
- ,TRUSTED=NO
- specifies whether the unit of work is a member of the trusted
computer base. Subsequent RACROUTE REQUEST=AUTH requests using an
ACEE with this attribute (or a token extracted from the ACEE) have
the following effects:
- Authorization checking is bypassed (this includes bypassing the
checks for security classification on users and data).
- No statistics are updated.
- No audit records are generated, except those requested using the
SETROPTS LOGOPTIONS command or the UAUDIT operand on the ALTUSER command.
- No exits are called.
Subsequent RACROUTE REQUEST=FASTAUTH requests using an ACEE
with this attribute (or a token extracted from the ACEE) have the
following effects: - Authorization checking is bypassed (this includes bypassing the
checks for security classification on users and data).
- No statistics are updated.
- No audit records are generated, except those requested using the
UAUDIT operand on the ALTUSER command.
This is similar to having the started procedures table
trusted bit on.
Note: The TRUSTED=YES keyword only has meaning
when SESSION=STARTED is also specified.
- ,USERID=userid addr
- specifies the user identification of the user who has entered
the system. The address points to a 1-byte length field, followed
by the user ID, which can be up to eight characters.
If the USERID=
keyword is omitted, "*" is the default.
To prevent a protected
user ID from being used to log on, RACROUTE REQUEST=VERIFY processing
checks if the protected user ID indicator is on in the user profile.
If the indicator is on, RACROUTE REQUEST=VERIFY fails unless keywords
such as PASSCHK=NO or START=PROCNAME have been specified to indicate
that no password is needed. If a password is expected to be specified
for a RACROUTE, it fails as an incorrect password attempt. This denies
users the ability to log on with a protected user ID using a password,
PassTicket, or OID card. RACROUTE REQUEST=VERIFY processing returns
the same RACROUTE return code, informational error message, and auditing
as done for a normal system entry attempt with an incorrect password.
However, the user profile is not updated, the revoke count is not
incremented or reset, and the user is not revoked for exceeding the
system limit for password attempts.
Application considerations: When
verifying a user ID and password from a user, validate that the user
ID and password are 1-8 characters in length and contain only characters
that are alphabetic, numeric, # (X'7B'), @ (X'7C'), or $ (X'5B'). Note: If
SETROPTS MIXEDCASE is not in effect, you must change the user ID,
password, and new password to uppercase. If SETROPTS MIXEDCASE is
in effect, you must change only the user ID to uppercase.
Certificate
user IDs:
Certificate authority certificates are associated
with the user ID irrcerta, MULTIID certificate name
filters are associated with the user ID irrmulti,
and site certificates are associated with the user ID irrsitec.
These user IDs cannot be used for any purpose other than anchoring
certificate authority certificates, site certificates, or certificate
name filters.
The irrcerta, irrmulti,
and irrsitec user IDs are defined to RACF during IPL in a manner similar to the method
used to define the user ID IBMUSER. These user IDs are added in revoked
status and are not connected to any groups, ensuring that they cannot
be used as valid user IDs. RACROUTE REQUEST=VERIFYs performed for
these user IDs fail due to the lack of connected groups.
Identity
context references:
An 8-byte user ID with a prefix of “**”
(X’5C5C’) and an 8-byte password indicate that the USERID and PASSWRD
parameters identify an identity context reference (ICR), not the user
ID and password of a user that has entered the system. There is no
change to the format of the user ID and password parameters.
When
an identity context reference is specified on a RACROUTE REQUEST=VERIFY,ENVIR=CREATE
request, and the SESSION=type is specified as (or defaulted to) IP,
OMVSSRV, TSO, or no session type, RACF attempts
to resolve the reference from the local identity context cache using
the R_cachserv callable service. It uses the identity context reference
supplied as the USERID and PASSWRD parameters to determine the appropriate
user ID, and other authentication information contained in an Identity
Context Extension block (ICTX). If an ICR is specified with a different
SESSION=type, RACF does not
attempt to resolve it and the request proceeds with all of the parameters
as specified.
When an ICR is specified for a valid session type, RACF does not utilize the following
keywords in its subsequent processing: JOBNAME, SGROUP, SUSERID, SNODE,
EXENODE, STOKEN, REMOTE, and START.
If the identity context
reference is successfully resolved to a user ID and ICTX block, PASSCHK
=NO will be set. PASSCHK=NO means that the following parameters will
not be utilized during the authentication check: ENCRYPT, OIDCARD,
PASSWRD, PHRASE, NEWPASS, or NEWPHRASE. RACF will
continue authorization checking of the resolved user ID and, if successful,
will build an ACEE that points to the ICTX block.
If the ICR
could not be resolved, RACF will
attempt to build an ACEE with the PASSCHK and USERID values as entered.
- X500NAME=X500 name pair addr
- specifies the data structure that contains the X.500 name pair
associated with this security environment. Before using the name pair,
you need to obtain it from the digital certificate associated with
the user ID. You can use the initACEE query function for this task.
The name pair must contain both the issuer's name and the subject's
name from the certificate.
The X500NAME parameter is valid only
for the ENVIR=CREATE function of a REQUEST=VERIFY request. However,
the ENVIR=CREATE function ignores the parameter or uses a different
name pair in certain circumstances: - The parameter is ignored if both the ENVRIN parameter and SYSTEM=YES
are specified.
- When creating an ACEE from an ENVR object, the ENVR object might
already contain an X.500 name pair, which is used.
- If a RACROUTE REQUEST=VERIFY, ENVIR=CREATE creates an ACEE for
an undefined user, the X500NAME parameter is ignored.
- If the RACROUTE REQUEST=VERIFY request creates an ACEE for a RACF defined user, the ACEE points
to a copy of the X.500 name pair structure in the same subpool as
the ACEE. This X.500 name is used in auditing.
When an A-type or RX-type notation is used, name pair
addr specifies the field name of the data structure. When
register notation is used, it specifies the register containing the
address of the data structure.
When specifying X500NAME=, you
must also specify RELEASE=7705 or later. The data structure of the
X.500 name pair is shown in Table 4.
Table 4. Description of X500NAME data structureOffset |
Length (bytes) |
Description |
---|
0 |
4 |
Length of entire X.500 name pair data structure |
4 |
2 |
Length of issuer's name (1–255) |
6 |
2 |
Length of subject's name (1–255) |
8 |
1–255 |
Up to 255 characters of the Issuer’s distinguished name, will
be truncated if longer |
* |
1–255 |
Up to 255 characters of the Subject’s distinguished name, will
be truncated if longer |
- ,MF=S
- specifies the standard form for the RACROUTE REQUEST=VERIFY macro
instruction.
Guidelines for changing or deleting an ACEE
Delete only an ACEE that you created. Issuing a RACROUTE REQUEST=VERIFY
with ENVIR=DELETE specified to delete the existing ACEE can lead to
problems if you were not the one who created that environment. The
issuer of the ENVIR=CREATE that built the ACEE might have saved a
pointer to it and might be expecting it to still be available later
in processing. Note that this is the case for the initiator's ACEE.
Also, if you delete an ACEE, you might lose tables anchored off that
ACEE that are needed later in RACF processing.
See z/OS Security Server RACF Diagnosis Guide for
overview diagrams of ACEEs and related control blocks. These diagrams
can be useful when diagnosing problems. Note: When
you delete an ACEE that has a third-party ACEE attached, the RACINIT
pre- or post-exits get control again for the third-party ACEE as well
as for the original ACEE being deleted.
If you make a copy of the ACEE and update fields, avoid passing
it to RACF. Many RACF services anchor tables off the ACEE and
refresh these tables when required. If you update fields in a copy,
the original ACEE contains incorrect pointers that result in abends
when the original is used or deleted. In general, it is recommended
that you do not copy an ACEE.
If you need to delete or change an ACEE that you did not create,
you can use one of the following methods. - Save and restore the current ACEE pointers:
- Save the current ACEE pointers from ASXBSENV and TCBSENV.
- Clear ASXBSENV and TCBSENV.
- Issue RACROUTE REQUEST=VERIFY ENVIR=CREATE.
- At the end of processing
- Issue ENVIR=DELETE
- Restore ASXBSENV and TCBSENV to the original values.
- Change the values in the current ACEE:
- Issue RACROUTE REQUEST=VERIFY with ENVIR=CHANGE to change the
values in the current ACEE.
- Create, anchor, and delete a third-party ACEE:
- Issue RACROUTE REQUEST=AUTH with USERID= and GROUPID=, causing RACF to create, anchor, and delete
a third-party ACEE internally.
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=VERIFY has completed successfully.
- RACF RC
- Meaning
- 00
- Indicates a normal completion.
- 04
- Verify token information.
- Reason Code
- Meaning
- 0C
- Indicates a TOKNIN was specified, but its length was too large.
- 10
- Indicates an STOKEN was specified, but its length was too large.
- 04
- Requested function could not be completed. No RACF decision.
- 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:
- ENVIR=VERIFY was specified without SAF installation exit processing.
- 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
- The user profile is not defined to RACF.
- 20
- RACF is not active.
- 58
- RJE or NJE operator FACILITY class profile not found.
- 08
- Requested function has failed.
- RACF RC
- Meaning
- 04
- The user profile is not defined to RACF.
- 08
- The password or password phrase is not authorized.
- 0C
- The password or password phrase has expired.
- 10
- At least one of the following conditions has occurred:
- The new password or password phrase is not valid.
- A new password phrase was specified with a current password, or
a new password was specified with a current password phrase.
- A new password phrase was specified with a PassTicket as the current
password, but the user does not currently have a password phrase.
- A password or password phrase change is disallowed at this time
because the minimum password-change interval has not passed.
- 14
- The user is not defined to the group.
- 18
- RACROUTE REQUEST=VERIFY was failed by the installation exit routine.
- 1C
- The user's access has been revoked.
- 24
- The user's access to the specified group has been revoked.
- 28
- OIDCARD parameter is required but not supplied.
- 2C
- OIDCARD parameter is not valid for specified user.
- 30
- The user is not authorized to the port of entry in the TERMINAL,
JESINPUT, or CONSOLE class.
- Reason Code
- Meaning
- 00
- Indicates the user is not authorized to the port of entry.
- 04
- Indicates the user is not authorized to access the system on this
day, or at this time of day.
- 08
- Indicates the port of entry cannot be used on this day, or at
this time of day.
Note: The port of entry refers to the TERMINAL class,
the JESINPUT class, and the CONSOLE class ports of entry.
- 34
- The user is not authorized to use the application.
- 38
- SECLABEL checking failed.
- Reason Code
- Meaning
- 04
- MLACTIVE requires a SECLABEL; none was specified.
- 08
- Indicates the user is not authorized to the SECLABEL.
- 0C
- The system was in a multilevel secure status, and the dominance
check failed.
- 10
- Neither the user's nor the submitter's security label dominates.
They are disjoint.
- 14
- The client's security label is not equivalent to the server's
security label.
- 44
- A default token is used as input token.
- 48
- Indicates that an unprivileged user issued a RACROUTE REQUEST=VERIFY
in a tranquil state (MLQUIET).
- 4C
- NODES checking failed.
- Reason Code
- Meaning
- 00
- Submitter's node is not allowed access to execution node.
- 04
- NJE failure: UACC of NONE for USERID type of NODES profile.
- 08
- NJE failure: UACC of NONE for GROUP type of NODES profile.
- 0C
- NJE failure: UACC of NONE for SECLABEL type of NODES profile.
- 10
- NJE failure: No local submit node specified.
- 14
- NJE failure: Reverification of translated values failed.
- 50
- Indicates that a surrogate submit attempt failed.
- Reason Code
- Meaning
- 04
- Indicates the SURROGAT class was inactive.
- 08
- Indicates the submitter is not permitted by the user's SURROGAT
class profile.
- 0C
- Indicates that the submitter is not authorized to the security
label under which the job is to run.
- 54
- Indicates that a JESJOBS check failed.
- 5C
- Indicates that an error occurred while retrieving data from the RACF database.
- Reason Code
- Meaning
- 0483yyyy
- An error occurred while RACROUTE REQUEST=VERIFY was accessing
the RACF data base. "yyyy"
is the RACF manager return
code associated with the abend that would have been issued.
- 64
- Indicates that the CHECK subparameter of the RELEASE keyword was
specified on the execute form of the RACROUTE REQUEST=VERIFY macro;
however, the list form of the macro does not have the same release
parameter. Macro processing terminates.
Example 1
Use the standard form of the macro to perform the
following tasks: - Create an ACEE for the user ID and its default group.
- Chain the ACEE off either the current TCB or ASXB, or both, by
not specifying the ACEE keyword.
- Verify that the user named USERNAME is a valid user.
- Verify that the password called PASSWORD is valid.
RACROUTE REQUEST=VERIFY ENVIR=CREATE,USERID=USERNAME, X
PASSWRD=PASSWORD,WORKA=RACWK
⋮
RACWK DS CL512
Example 2
Use the standard form to perform the following
tasks: - Verify that the user named USERNAME is a valid user.
- Verify that the group named GROUPNAM is a valid group.
- Verify that USERNAME is defined to the group.
- Create an ACEE for the user and group and put its address in ACEEANCH.
- Specify that the user's password is not required.
RACROUTE REQUEST=VERIFY,ENVIR=CREATE,USERID=USERNAME, X
GROUP=GROUPNAM,ACEE=ACEEANCH, X
PASSCHK=NO,WORKA=RACWK
⋮
RACWK DS CL512
Example 3
Use the standard form of the macro to delete the ACEE of the current
task or address space, or both.
RACROUTE REQUEST=VERIFY,ENVIR=DELETE,WORKA=RACWK
⋮
RACWK DS CL512
|