The RACROUTE REQUEST=EXTRACT Call

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

The RACROUTE REQUEST=EXTRACT Call

The RACROUTE REQUEST=EXTRACT call:

Extracts user information from the security file
Encrypts data using a hashing technique or the DES algorithm
Creates encrypted passwords that can be specified as input to RACROUTE REQUEST=VERIFY (ENVIR=CREATE)

To return an encrypted password for any user whose submitting ACID has the authority to submit jobs on behalf of another user’s ACID, enter the command:

TSS PERMIT(USER) ACID(OTHER)

CA Top Secret supports a form of extract that returns a feedback area when used in WARN mode if the FIELDS parameter is coded as follows:

F'1',C'PASSWORD',C'TSS '

This extract indicates whether a user is also authorized to submit a job using another user's ACID.

To issue a RACROUTE REQUEST=EXTRACT call, the caller must be executing authorized—APF, system key (keys 0 through 7), or supervisor state.

Upon return from a RACROUTE REQUEST=EXTRACT call with the TYPE=EXTRACT parameter, general purpose register 1 points to a response area. It is your responsibility to free this storage area. The storage is obtained in the subpool specified on the macro invocation, with the default subpool being 229. The storage key obtained depends on the subpool.

The extract request searches the user record of the selected ACID for any fields to be extracted. If a field is not found in the user record, the search continues with the first connected profile in the ACID’s list. This allows you to assign security related fields to a role based profile that can be added to any user.

Password Encryption

RACROUTE REQUEST=EXTRACT is used by the IBM's BDT to obtain an encrypted password from a RACF file and pass it over the network to another RACF site where the same user's password exists on the other site's Security File. CA supports this function if the two remote sites have CA Top Secret and the same encryption key applied using the TSSKEY00 utility.

Using the encrypt function of RACROUTE REQUEST=EXTRACT, password re‑authentication is possible. If a password for a user is encrypted using the DES function of RACROUTE REQUEST=EXTRACT, it is encrypted to the same value as would be returned from the RACROUTE REQUEST=EXTRACT extract function.

Consider the following VTAM application example:

The user has signed on.
At some point in processing re‑authentication is required, and the application prompts the user for the password.
The password entered by the user is encrypted using:
```
RACROUTE REQUEST=EXTRACT,TYPE=ENCRYPT
```
The DES function encrypts the user's password; assume this is placed in PASSA.
The application then issues which returns the signed‑on user's password encrypted; assume this is placed in PASSB:
```
RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT
```
PASSA and PASSB are then compared. If they are the same, then the user is authenticated. (Note that the clear text password is not returned by RACROUTE REQUEST=EXTRACT.)

Obtaining Feedback

To obtain feedback from RACXTRT, enter:

RACROUTE  REQUEST=EXTRACT,
          TYPE=EXTRACT,
          SUBPOOL=1,
          FIELDS=XFIELDS,
          WORKA=RACWK,
          ENTITY=XUSER
XFIELDS  DC    F'1',C'PASSWORD',C'TSS '
XUSER    DC    CL8'USERID'

SUBPOOL=1 obtains storage for response in the user's TCB key. It is your responsibility to free the response area.

For FAIL and IMPLEMENT modes, the return code is 8 if the user is not authorized, and a value of 9D appears in Register 0. The ACID is not authorized by CA Top Secret to extract passwords or to submit jobs on behalf of other users.

In WARN mode, since the value for both Register 15 and Register 0 is 0, the only way to determine if the ACID is authorized to extract passwords and submit jobs on behalf of other ACIDs is through the feedback area. This area follows the encrypted password field mapped by #FEEDBCK in Optional Materials, and #RXTRESP maps the response area.

Information Feedback

The INSTLN operand of any security macro can obtain information feedback. Feedback consists of return codes, access masks, and message text. It allows a caller to make informative decisions about access attempts and the security environment. The field is a minimum of 16 bytes, a maximum of 255 bytes.

INSTLN must address a data area that is modifiable using the caller's protect key. The format of the feedback area is:

+0 (4) FEEDBACK ID

Characters TSSF indicate CA Top Secret user feedback.

+4 (1) LENGTH

Indicates the size of the feedback area.

Range: 16 to 255

+5 (1) RETURN CODE

The actual return code; the code that would have been returned to register 15 if the event was processed in FAIL or IMPLEMENT mode. The code is always returned to the feedback area, even if you are running in WARN or DORMANT mode.

+6 (1) VIOLATION CODE

The detail error reason code, 1 to 255, that reflects the type of violation.

+7 (1) REQUESTED ACCESS

Indicates the type of requested access.

+8 (1) ALLOWED ACCESS

Indicates the type of access that was granted.

+9 (1) FLAG BYTE

Used both by the caller, to control processing, and by CA Top Secret, to feed information back.

The caller can set the NOLOG x'10' bit to prohibit CA Top Secret from automatically logging the request.

CA Top Secret sets the terminate user bit, x'08', when the user's violation count has exceeded the VTHRESH threshold. This informs the caller to cancel the session.

The flag byte should be cleared to hexadecimal zeros and set prior to each call because CA Top Secret will set the flags during each call. If the flag byte is not reset, incorrect results may occur. The flags and their meanings are:

B'10000000': User ACID is undefined
B'01000000': Default ACID used
B'00100000': Password was changed
B'00010000': Do not log this call
B'00001000': Terminate this user
B'00000100': Reserved
B'00000010': Reserved
B'00000001': Reserved

+10 (1) USER'S MODE

The user's MODE is returned by CA Top Secret. It can be used to determine whether to fail the request. The current MODE of the user is returned as:

x'80': DORMANT
x'40': WARN
x'20': FAIL
x'30': IMPL (10+20)

+11 (1) MESSAGE COUNT

Indicates how many messages were returned in the MESSAGE SEGMENTS area; +26.

+12 (14) RESERVED

Reserved. This field must be initialized to zeroes prior to each security call.

+12 (?) MESSAGE SEGMENTS

Message segments of generated messages.

The format is: +0(2)=length; +2(?)=message segment. This will contain various messages—including the last‑used message for RACINIT. A message segment example appears below.

+26(2) = 53

+28(53) = TSS9500E DUF/EXTRACT FAILED‑USER HAS NO (INST) DATA

+81(2) = 42

+83(44) = TSS9506E PROBABLE SITE INTERFACING ERROR 030

All lengths and offsets are in decimal, not hexadecimal, format.

Message text is only returned if the feedback area size will hold the text. RACROUTE REQUEST=FASTAUTH supports a feedback area of 256 bytes in length.

Register 15 Return Codes

The return codes set in register 15 versus the feedback return codes are:

R15	FDBRC	FDBDRC	Meaning
0	0	0	Access was allowed
4	4	0	Resource not defined; DORMANT mode
5	4	^0	CLASSname not defined; DRC(NOVIOL)
4	>4	^0	WARN mode
>4	>4	^0	Fail access

For most applications, testing the register 15 code is sufficient. A return code of 0 allows the request, a return code of 4 defers to whatever native security is available, and a return code greater than 4 fails the request.

Certain fields are set in the 16 word work area provided for RACROUTE REQUEST=FASTAUTH and FRACHECK:

Word 12 = 0 No audit
Word 12 = 4 User/resource/facility is audited

Word 13 = Same as register 15 return code