RACROUTE REQUEST=VERIFY (standard form)

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

If an address is specified, the address must point to an 8-byte application name, left-justified, and padded with blanks if necessary.

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.

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.

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.

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.

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.

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.

Applications should fold the group name to uppercase.

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.

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.

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.

When specifying ICRX=, you must specify RELEASE=7760 or later.

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.

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.

When specifying IDID=, you must specify RELEASE=7760 or later.

An application can request that RACROUTE generate an IDT when authenticating a user. An application can also specify an IDT in place of other authentication credentials like a password.

For a complete overview on how to activate and use the IDTA parameter, see Activating and using the IDTA parameter in RACROUTE REQUEST=VERIFY.

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.

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.

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.

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.

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.

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.

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

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.

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.

To use this keyword, you must specify RELEASE=1.9 or a later release number.

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.

Rule: When both the POE and SERVAUTH parameters are specified, SERVAUTH is ignored.

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.

YES

RACROUTE REQUEST=VERIFY processing makes other tasks for the job step non-dispatchable.

NO

The step-must-complete function is not used.

If START is specified, PASSWRD and OIDCARD should not be specified.

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.

Applications should fold the submitting user ID to uppercase.

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.

EXENODE      NESTED       OIDCARD      SGGROUP     STOKEN      TOKNIN      
JOBNAME      NEWPASS      REMOTE       SNODE       SUSERID     NEWPHRASE      IDTA

When ENVRIN is specified, the indicated keywords are ignored, therefore the “fastpath” benefit is recognized.

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.

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

This is similar to having the started procedures table trusted bit on.

If the USERID= keyword is omitted, * is the default.

When the IDTA is specified with a supplied IDT, the USERID parameter may be omitted. In this case, the "sub" claim value from the IDT is used as the effective USERID.

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.

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.

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.