Overview
EASY/Exit supports RACF exit points and enforces rule-based policies for authentication and password/passphrase processing. Supported RACF entry points include RACINIT pre/post (ICHRIX01/ICHRIX02), new-password (ICHPWX01), and new-passphrase (ICHPWX11). On each entry, &ENV = RACF and &ENVS contains the subenvironment name.
Enabling the RACF environment
Install EASY/Exit RACF interface stubs into an LPA library (for example, SYS1.LPALIB) so RACF loads the stubs at IPL. Only the stubs for the desired exits must be copied. After IPL, start DIF; changes to rules thereafter require only a DIF refresh (for example, F DIF,REFRESH EXT).
//RACF EXEC PGM=IEWL,PARM='XREF,LIST,LET,RENT',REGION=4M
//SYSPRINT DD SYSOUT=*
//SYSLMOD DD DSN=SYS1.LPALIB,DISP=SHR
//SYSLIB DD DSN=dif.load.library,DISP=SHR
//SYSLIN DD *
INCLUDE SYSLIB(EXTRIX02) ENTRY ICHRIX01
NAME ICHRIX01(R)
INCLUDE SYSLIB(EXTRIX02) ENTRY ICHRIX02
NAME ICHRIX02(R)
INCLUDE SYSLIB(EXTRIX02) ENTRY ICHPWX01
NAME ICHPWX01(R)
INCLUDE SYSLIB(EXTRIX02) ENTRY ICHPWX11
NAME ICHPWX11(R)
Enable the environment in rules with:
DEFENV RACF MODE(ACTIVE)RACF subenvironments
The RACF environment contains subenvironments (stored in &ENVS) representing specific RACF exits. The common subenvironments are:
- ICHRIX01 — RACINIT pre-processing (before user identification).
- ICHRIX02 — RACINIT post-processing (after identification).
- ICHPWX01 — New-password processing (password change requests).
- ICHPWX11 — New-passphrase processing (z/OS 1.8+; 9–100 chars).
RACINIT variables (ICHRIX01 / ICHRIX02)
The table below summarizes primary variables available in the RACINIT pre/post environments. Many general DIF variables (for example, &JOBNAME, &SYSID, &CURDATE) are also available.
| Name | Values | Description |
|---|---|---|
| ENV | RACF | Environment name |
| ENVS | ICHRIX01 / ICHRIX02 | Subenvironment name |
| RACINIT_FUNCTION | CHANGE / DELETE / CREATE | Type of RACINIT function |
| RACINIT_PASSCHK | YES / NO | Indicates whether password checking should be performed |
| RACINIT_RETRY | YES / NO | Request a retry of the RACROUTE VERIFY (set after adjusting variables) |
| RACINIT_UID | 8 char | TSO userid for which RACINIT was issued |
| RACINIT_RC | 0–255 | RACINIT return code |
| RACINIT_NEWPASS | 8 char | New password (where available) |
New-password variables (ICHPWX01)
ICHPWX01 is entered for password-change requests (TSO PASSWORD, ALTUSER, programmatic VERIFY with new password). Not all variables are present for every invocation (for example, current password may be unavailable for ALTUSER).
| Name | Values | Description |
|---|---|---|
| ENV | RACF | Environment |
| ENVS | ICHPWX01 | Subenvironment |
| RACPW_FUNCTION | VERIFY / ALTUSER / PASSWORD | Source of password change |
| RACPW_EXITRC | 0,4,8,12,16 | Return code to return to the system; use to allow/reject changes |
| RACPW_UID | 8 char | Userid whose password is to be changed |
| RACPW_NEWPASS | 0–8 char | Requested new password (may be null) |
| RACPW_NEWPASSL | 0–8 | Length of requested new password |
| RACPW_CURPASS | 0–8 | Current password (may be null) |
| RACPW_FORMAT | CLEAR / ENCRYPT / PASSTICKET | Format of new password; rules typically ignore ENCRYPT/PASSTICKET unless RACPW_ENCRYPOK = YES |
| RACPW_INTERVAL | 0–255 | Password-change interval (0 if not specified) |
| RACPW_REJECT | YES / NO | Set to YES to reject the new password |
| RACPW_ENCRYPOK | YES / NO | Allow processing when new password format is encrypted or passticket |
New-passphrase variables (ICHPWX11)
ICHPWX11 handles passphrases (9–100 characters). This subenvironment is entered for passphrase requests (TSO PHRASE, ALTUSER, ADDUSER, or programmatic VERIFY specifying a new passphrase). Note: RACF performs minimum checks before calling ICHPWX11; invalid passphrases are rejected by RACF and never reach this subenvironment.
| Name | Values | Description |
|---|---|---|
| ENV | RACF | Environment |
| ENVS | ICHPWX11 | Subenvironment |
| RACPW_FUNCTION | VERIFY / ALTUSER / ADDUSER / PHRASE | Source of passphrase change |
| RACPW_EXITRC | 0 / 4 / 8 | Return code (0 allow, 4 fail, 8 fail and suppress messages) |
| RACPW_NEWPASS | 9–100 char | New passphrase |
| RACPW_NEWPASSL | 9–100 | Length of new passphrase |
| RACPW_REJECT | YES / NO | Set to YES to reject the passphrase |
| RACPW_NALPHA / RACPW_NNUMER / RACPW_NNATL / RACPW_NBLANK | 0–100 | Counts of alphabetic, numeric, national characters, and blanks in the new passphrase |
Minimum RACF checks (examples): userid must not be part of the passphrase; at least two alphabetic and two nonalphabetic characters; no more than two identical consecutive characters. Passphrases failing minimum checks are rejected by RACF before ICHPWX11 is invoked.
Additional RACF-related variables
Other useful variables available in RACF exits include:
| Name | Values | Description |
|---|---|---|
| JOBNAME | 8 char | TSO userid or batch job name requesting the change |
| JOBTYPE | JOB / TSU / STC | Type of process requesting the change |
| JOBNUM | TSUnnnnn / JOBnnnnn / MSTR | JES job id string |
| PGM | 8 char | Program requesting the change |
| RUSER / RGROUP | 8 char | RACF userid / default group of the requesting user |
| RACF_U_CONNG | 8 char | RACF connect group of the user |
LOGONBY (surrogate) processing
EASY/Exit can implement surrogate logon rules that allow protected/shared userids to be used via authority checks (for example, check that the surrogate has READ on LOGONBY.userid in the SURROGAT class). Typical logic blank-outs the GROUP field, skips further password checking, and requests a RACINIT retry.
DEFRULE LOGONBYRULE
IF &ENV = RACF &ENVS = ICHRIX02 &JOBTYPE = TSU
&RACI_UID = (SHARED1,SHARED2)
&RACI_GROUP = (USER1,USER2)
&RACI_FUNCTION = CREATE &RACI_PASSCHK = YES
THEN SET &RACI_GROUP = ' '
SET &RACI_PASSCHK = NO
SET &RACI_RETRY = YES
Key LOGONBY variables:
| RACI_LOGONBYCL | 1–8 | Resource class used for surrogate check |
| RACI_LOGONBYNM | 1–255 | Resource name used for surrogate check |
| RACI_LOGONBYOK | YES / NO | Indicates whether password & authority checks passed |
| RACI_LOGONBYRC / RACI_LOGONBYRS | numeric | Return and reason codes from resource check |
Examples
DEFRULE FTPRULE
IF &ENV = RACF &ENVS = ICHRIX02
&RACINIT_UID = FTP* &RACINIT_APPLN = FTPD*
&RACINIT_FUNCTION = CREATE &RACINIT_PASSCHK = YES
&RACINIT_RC = 12
THEN SET &RACINIT_PASSCHK = NO
SET &RACINIT_RETRY = YES
DEFRULE PWCHGRUL
IF &ENV = RACF &ENVS = ICHPWX01
&RACPW_UID = SJP* &RACPW_FUNCTION NE ALTUSER
&RACPW_NEWPASS NE '' &RACPW_CHNGDAYS = 0
THEN SET &RACPW_REJECT = YES
ISSUE WRITEMSG(REJMSG)
DEFMSG REJMSG 'DTS001 PASSWORD CAN BE CHANGED ONLY ONCE PER DAY'
DEFRULE PWTEST
IF &ENV = RACF &ENVS = ICHPWX01 &RACPW_NEWPASS NE ''
THEN DO
IF &RACPW_NEWPASSL LT 5 THEN SET &RACPW_REJECT = YES ISSUE WRITEMSG(REJMSG2)
IF &RACPW_NEWPASS = (TEST,LOGON,PASSWORD) THEN SET &RACPW_REJECT = YES ISSUE WRITEMSG(REJMSG3)
END
DEFMSG REJMSG2 'DTS002 MINIMUM PASSWORD LENGTH IS 5 CHARACTERS'
DEFMSG REJMSG3 'DTS003 PASSWORD NOT ALLOWED'
DEFRULE PPTEST
IF &ENV = RACF &ENVS = ICHPWX11
THEN DO
IF &RACPW_NALPHA LT 4 OR &RACPW_NNUMER LT 4 OR &RACPW_NBLANK LT 2 OR &RACPW_NNATL LT 1
THEN SET &RACPW_REJECT = YES ISSUE WRITEMSG(M1)
END
DEFMSG M1 "NEW PASSPHRASE DOES NOT MEET STANDARDS"
Debugging and operational notes
Use standard DIF tracing and SMF mechanisms to record rule activity. For rules that modify behavior dynamically, remember to refresh in-storage rules with F DIF,REFRESH EXT. When writing rules that emit messages or issue additional RACF calls, take care to avoid recursion and to handle encrypted/pass-ticket password formats appropriately (RACPW_FORMAT).