RACROUTE REQUEST=VERIFY (standard form)

The standard form of the RACROUTE REQUEST=VERIFY macro is written as follows.

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.
For a description of additional parameters that are required and additional keywords that you can code on the RACROUTE request, but that are not specific to this request type, see RACROUTE (standard form).



`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
,PASSCHK=NOMFA

,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
Notes: 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.
If a RACF password is encrypted using KDFAES, then the data that is specified by the PASSWRD= keyword must be encoded using the DES method to be evaluated successfully. If SETROPTS PASSWORD(ALGORITHM(KDFAES)) is active, then the data that is specified by the NEWPASS= keyword must be encoded using the DES method to create a new password that is correctly evaluated.
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.

Table 1. Description of ENVR data structure
Description	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 processing
ENVR 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= values
Release	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 in the z/OS Internet library.

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:

ACEE
SUBPOOL
LOC

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:

If the ICRX contains an ICR and the ICR is resolved, VERIFY retrieves an ENVR object for the user. The ENVR object is used to create an ACEE for the caller in a way that is similar to how the ENVRIN parameter is specified on RACROUTE REQUEST=VERIFY. In this case, the IDID within the ICRX is ignored and reverification of information is not performed.
Note: When creating an ACEE using an ENVR object, the ENVR object might already contain an IDID.
If the ICRX contains an ICR but the ICR cannot be resolved and if section 2 of the IDID, which is reserved for exclusive use by the External Security Manager, specify a specific user ID, then VERIFY processing continues with this user ID and other security relevant information within section 2 of the IDID. If section 2 of the IDID does not exist or does not specify a RACF user ID, RACROUTE REQUEST=VERIFY fails the request and returns "user not defined".

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 in the z/OS Internet library.

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 in the z/OS Internet library.

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:

If both the ENVRIN parameter and SYSTEM=YES parameter are specified.
Note: When creating an ACEE using an ENVR object, the ENVR object might already contain an IDID.
If a RACROUTE REQUEST=VERIFY, ENVIR=CREATE creates an ACEE for an undefined user, the IDID parameter is ignored.

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. However, the application should code the password- and phrase-related keywords as appropriate depending on the length of user-entered data, and let RACROUTE determine its validity.

Application considerations: When verifying a new password, validate that it is 1-8 characters in length. If SETROPTS MIXEDCASE is not in effect, you must change the password to uppercase. Avoid performing any other checking of character content, letting the security product determine the validity of the password.

,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 SETROPTS PASSWORD(ALGORITHM(KDFAES)) is active, or 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. However, the application should code the password- and phrase-related keywords as appropriate depending on the length of user-entered data, and let RACROUTE determine its validity.

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

,PASSCHK=NOMFA

specifies whether the user's password, password phrase, MFA credentials or OIDCARD is to be verified.

YES

RACROUTE REQUEST=VERIFY verifies the user's password, password phrase, MFA credentials 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.

For a user subject to multi-factor authentication (MFA), RACF passes the contents of the PASSWRD=, NEWPASS=, PHRASE=, and NEWPHRASE= keywords to the MFA started task, where they are evaluated as MFA credentials. If the credentials are unable to be evaluated as MFA credentials (for example, if the MFA started task is unavailable), they are evaluated as RACF credentials if the user is allowed to fall back to password-based authentication.

NO

The user's password, password phrase, MFA credentials or OIDCARD is not verified. And, if the logon is successful, no message is issued.

NOMFA

Same as YES, except password and password phrase parameters are always verified as a password or password phrase, not as MFA credentials, even for users who have an active MFA factor.

Use of the PASSCHK=NOMFA parameter requires that RELEASE=1.9 or later be specified.

,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.

Application considerations: When verifying a password, validate that it is 1-8 characters in length. If SETROPTS MIXEDCASE is not in effect, you must change the password to uppercase. Avoid performing any other checking of character content, letting the security product determine the validity of the password.

,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 When SESSION=SYSAS is specified, SAF builds a default ACEE.	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=VERIFYX. This parameter also controls whether a message is to be issued when the RACROUTE REQUEST=VERIFYX is successful.

The default is ASIS.

Note: Messages are always issued if the RACROUTE REQUEST=VERIFYX processing is unsuccessful.

ASIS

The messages and statistics are controlled by the installation's current options on the RACF SETROPTS command.

Notes:

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 RACROUTE REQUEST=VERIFYX 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).

STAT=NO does not update the LAST-ACCESS attribute of the RACF user entity thus removing the ability of an auditor from determining when this id was last (if ever) authenticated. This is the case with DB/2.

,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 in the z/OS Internet library.

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.
There are installation exit considerations when specifying SYSTEM=YES. See z/OS Security Server RACF System Programmer's Guide, RACROUTE REQUEST=VERIFY(X) Exits for more information.

,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, be sure to validate that it contains only characters that are alphabetic, numeric, # (X'7B'), @ (X'7C'), or $ (X'5B')and is 1-8 characters in length. Additionally, you must change 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 structure
Offset	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:
1. Save the current ACEE pointers from ASXBSENV and TCBSENV.
2. Clear ASXBSENV and TCBSENV.
3. Issue RACROUTE REQUEST=VERIFY ENVIR=CREATE.
4. At the end of processing
  1. Issue ENVIR=DELETE
  2. 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.

68

Indicates that an error occurred while processing an MFA request.

Reason Code: Meaning
0004yyyy: An error occurred while RACROUTE REQUEST=VERIFY was processing the results of an MFA authentication request. "yyyy" contains diagnostic data.

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