Extending Security Through the z/OS Security Interface › The RACROUTE REQUEST=VERIFY Call

The RACROUTE REQUEST=VERIFY Call

Use RACROUTE REQUEST=VERIFY to:

• Request authorization checking for a job, session, and STC initiations
• Support signon validation for individual users, including password validation
• Create a temporary security environment for third party authorization checking
• Delete the security environment ACEE at job, session, and STC termination

When executing in a facility with AUTHINIT option, the application must run APF authorized in order to execute RACROUTE REQUEST=VERIFY.

We recommend running with the AUTHINIT option at all times.

In response to a RACROUTE REQUEST=VERIFY call, CA Top Secret builds an Accessor Environment Element (ACEE) and loads security record(s) if the initiation is allowed. These records are then used for further security checks during the job or session.

Examples: RACROUTE REQUEST=VERIFY

This example defines the RACROUTE REQUEST=VERIFY call to validate user signon:

RACROUTE REQUEST=VERIFY,    (Specify RACROUTE request type)
ENVIR=CREATE,               (Request Signon/Environment Create)
USERID=uid‑loc,             (Identifies user)
PASSWRD=pw‑loc,             (User's password, if supplied)
NEWPASS=newpw‑loc,          (User's new password, if supplied)
TERMID=term‑loc,            (Terminal name)
ACEE=acee‑anchor,           (See discussion in next section)
WORKA=work‑addr             (512 byte work area required by SAF)

This example defines the RACROUTE REQUEST=VERIFY call to process user log off:

RACROUTE REQUEST=VERIFY,    (Specify RACROUTE request type)
ENVIR=DELETE,               (Request deletion of ACEE / signoff)
ACEE=acee‑anchor            (Provide ACEE anchor address)

ACEE= Parameter Requirements

For the RACROUTE REQUEST=VERIFY call, the following requirements apply for the ACEE= parameter. For CA Top Secret to:

• Manage the ACEE, omit the ACEE= keyword. CA Top Secret anchors the ACEE in the TCBSENV field of the current TCB. In this case it resides below the 16 megabyte line (24 bit storage).
• Not manage (automatically locate) the ACEE, code ACEE=. The address you provide is a location (place holder) that CA Top Secret uses to return the address of the ACEE for a successful RACROUTE REQUEST=VERIFY with ENVIR=CREATE. In the case of a RACROUTE REQUEST=VERIFY with ENVIR=DELETE, the ACEE= parameter is the address of the anchor that points to the ACEE to be deleted. For all other RACROUTE requests, the ACEE parameter points to the ACEE itself.

The ACEE resides above the 16 megabyte line only when ACEE= has been coded and the caller is executing in a 31 bit addressing mode.