Profile extract functions

Note:
  1. This section does not include ADMN_XTR_PWENV (extract a password envelope), ADMN_XTR_PPENV (extract a password phrase envelope), and ADMN_XTR_SETR (SETROPTS extract).
  2. A REXX interface to the profile extract functions is available. This program, named IRRXUTIL, is designed to be invoked by REXX in problem state, and converts the output of an R_admin extract request to a set of REXX stem variables. For more information, refer to z/OS Security Server RACF Macros and Interfaces.

This set of function codes allows you to extract RACF® profile information from USER, GROUP, CONNECT, DATASET and general resource profiles. Note that CONNECT is a logical class that returns the details of a specific user-to-group connection. The extract functions return the entire profile; you cannot specify a list of segments, or fields, to be returned. You can, however, request that only the BASE segment be returned, or that the profile name only be returned.

The output (returned in the Out_message_strings parameter) consists of a header followed by a series of segment descriptors, which are followed in turn by a series of field descriptors, such as:
Figure 1. Extract functions output
Extract functions output
Note: These segment and field descriptors are not the same format as the segment and field entries described in the preceding for the update functions and SETROPTS extract. The term descriptor is used in order to highlight this distinction.

The header identifies the total length and subpool of the output block, the profile and class name of the data being returned, and the number of segments (and hence segment descriptors) which exist for the profile. Each segment descriptor contains the number of field descriptors being returned for that segment, and an offset to the first field descriptor for that segment. Each field descriptor contains the length of, and offset to, the data for the field. All of the field descriptors for a given segment will be contiguous. The mappings for this structure can be found in the IRRPCOMP macro.

The field descriptors return character data, not the raw data as it exists within the RACF database. The data is returned exactly as it is expected on input to a RACF command, or to the R_admin update functions. Also, data is returned for some profile fields even though they cannot be directly altered by a RACF command. For most of these fields, the data is returned in the same format which is displayed by the associated RACF listing command. The exception is for date fields. All dates are returned in mm/dd/yy format, to maintain consistency with the way dates are expected as input to commands.

See Table 3 for the fields associated with each profile type. For details on RACF profiles, segments, and fields, see z/OS Security Server RACF Macros and Interfaces. Only a subset of the defined fields are returned, as is detailed within the following field tables. Mostly, the RACF command keywords map to database fields. See the z/OS Security Server RACF Command Language Reference for syntax rules regarding the format of the data expected by the commands, and the format of the data returned by the R_admin extract functions.

For extract user, extract group, extract data set, and extract resource, there is a corresponding extract-next function code. These allow you to iteratively retrieve all RACF profiles of a given type for which you are authorized (this can be viewed as a hybrid between the LISTUSER * command, for example, and RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN). For each request, RACF extracts and returns the next profile that contains at least one field that the caller is authorized to see (using the rules applied by the LISTUSER, LISTGRP, LISTDSD, or RLIST command) after the profile that was specified in the parameter list header.

Notes:
  1. When using extract-next to return all general resource profiles for a given class, all the discrete profiles are returned, followed by the generic profiles. An output flag indicates if the returned profile is generic. A flag can be specified in the parameter list to request only the generic profiles in a given class. If only the discrete profiles are desired, check the output flag indicating whether the returned profile is generic. If it is, ignore the entry and terminate your extract-next processing.
  2. When using extract-next to return all data set profiles, generic and discrete profiles are interspersed. For each high level qualifier, generic profiles are returned first (in alphabetic order), followed by discrete profiles (in alphabetic order). When multiple discrete profiles exist for a single name, they are returned in the order in which they exist on the RACF database.
  3. For a caller with little RACF authority, a large amount of I/O may be performed against the RACF database until such a profile is located. This is no different from the LISTUSER *, LISTGRP *, or RLIST class-name * command. The IRR.RADMIN.LISTUSER, IRR.RADMIN.LISTGRP, and IRR.RADMIN.RLIST resources in the FACILITY class can be used to limit which users are allowed to use the extract and extract-next interfaces.
  4. The following are characteristics of the extract functions:
    • Are not subject to the 4096 limit on output lines like the list functions described.
    • Provide similar functions as ICHEINTY LOCATE and RACROUTE REQUEST=EXTRACT, but do not provide all of the functions provided by those interfaces.
    • Run in the caller's address space, not in the RACF address space. Therefore, are faster than the R_admin list functions and do not contend with other functions, such as the RACF Remote Sharing Facility, for RACF subsystem address space resources.
    • Are available to problem state callers, and require the same authority as do the corresponding RACF commands (e.g. LISTUSER), plus the FACILITY class check enforced by R_admin. Supervisor state callers can choose to bypass command authorization checking. The FACILITY check is not enforced for supervisor state callers by default. However, the caller can request that the check be performed.
The following header mapping is used both as input, for the caller to identify the requested profile, and as output, for RACF to return the profile data.
Note: These are two separate pieces of storage and RACF will not modify the caller's input storage.
Note: All offsets are relative to the start of the extract output block.
Table 1. Profile extract parameter list (input and output)
Offset Length Description
0 4 Eye catcher to aid in virtual storage dumps: 'PXTR'
4 4 Total length of the output buffer
8 1 Subpool of output buffer (specified by caller in Out_message_subpool parameter )
9 1 Parameter list version
10 2 Reserved
12 8 Class name (uppercase and padded with blanks). Class names cannot be abbreviated.
20 4 Length of profile name (maximum of 8 for users and groups; maximum of 17 for connects; maximum of 44 for data sets; maximum of 246 for general resources)
24 2 Reserved
26 6 The volume on which the data set resides. Binary zeros or blanks means it is not specified. If specified, the field must be padded with blanks if the volume is less than 6 characters.

On output, for a multi-volume data set, this field contains the first volume in the volume list. In all cases, the complete volume list is returned as a field in the BASE segment.
32 4 Duplicate discrete data set count. When using extract-next to cycle through the data set profiles, the caller should not alter this field.
36 4 Flag word
Note: RACF only propagates the "generic" flag (X'10000000') into the output version of the parameter list. When using extract-next, the caller must set the other flags as appropriate in the parameter list before calling R_admin for the next iteration.
  x'80000000' Bypass command processor (e.g. LISTUSER) authorization checking. Available for supervisor state callers only.
  x'40000000' Extract BASE segment only. By default, RACF will extract all profile segments, resulting in an I/O operation for each segment.
  x'20000000' For supervisor state callers, enforce the FACILITY class authorization check. By default, the FACILITY check is bypassed for supervisor state callers.
  X'10000000' For general resource requests:
On input:
  • For extract requests: return the profile which covers the input profile name if there is no exact match. By default, if there is no exact match on profile name, a "not found" return code combination (4/4/4) will be returned. Note that the class must be active, and SETROPTS GENERIC must be in effect for the class, in order for a generic match to be found.
  • For extract-next requests: return the next alphabetic generic profile in the class with respect to the input name (regardless of whether the input profile is generic or discrete). To retrieve the first generic profile in a class, the caller can provide a resource name consisting of a single blank (X'40').

On output: indicates that the profile returned by RACF is generic. When using extract-next to cycle through profiles, the caller should not alter this bit.

For DATASET requests:

On input:
  • For extract requests: return the generic profile that exactly matches the input profile name. If this bit is set for a profile with no generic characters, a fully qualified generic profile will be extracted instead of a discrete. It does not need to be set on to extract a profile containing generic characters.

    When the bit is off, and the input profile name contains no generic characters, only a discrete profile will be returned, if it exists. If a volume is not specified, and multiple discrete profiles exist for the specified name, RACF will return the first one, along with return codes 0/0/4 to indicate that additional profiles exist. To get the additional profiles, the caller can initiate a series of extract-next requests, passing in the unmodified parameter list that is returned, and stopping when the returned profiled name differs from the original name.

On output: indicates that the profile returned by RACF is generic. When using extract-next to cycle through profiles, the caller should not alter this bit.
  X'08000000' Uppercase the input name as appropriate. When the CLASS is USER, GROUP, CONNECT, DATASET, or a general resource class which has been defined as CASE(UPPER), R_admin will upper-case the input name before attempting to extract it. This flag is ignored for extract-next requests.
  X'04000000' Return only the profile name, without any of the profile data On return, the field at offset 40 containing the number of returned segments will be zero. If the "base-only" flag (x'40000000') is also specified, "name-only" will take precedence.
  X’02000000’ For DATASET requests:

On input for extract requests: return the profile which covers the input data set name on the specified volume.

If no discrete profile exists for the name, the covering generic profile will be returned if one exists. For a tape data set, only a generic profile will be returned, even if a discrete profile exists.

The specified data set must exist or return code 4/4/4 (profile not found) will be returned. If a volume is not specified, the data set must be cataloged.

When this bit is specified, ADMN_PROF_GENERIC is ignored.

This flag is ignored for extract-next requests.
40 4 Number of segments (including base)
44 16 Reserved
60 0 The start of the profile name. For extract connect, the profile name is <userID>.<group>. On output, the first segment descriptor starts immediately after the profile name.
Table 2. Segment descriptor mapping
Offset Length Description
0 8 Segment name (uppercase and padded with blanks)
8 4 Flag word
12 4 Number of fields for this segment (a list field header together with all its subfields are considered one logical field).
16 4 Reserved
20 4 Offset to first field descriptor for this segment
24 16 Reserved
40 0 Start of next segment descriptor, or, if last segment descriptor, start of field descriptors
Table 3. Field descriptor mapping
Offset Length Description
0 8 Field name (uppercase and padded with blanks)
8 2 Field type
  '8000'x Member of a repeat group
  '4000'x Reserved
  '2000'x Flag (boolean) field
  '1000'x Repeat field header. This descriptor contains the number of occurrences of the repeat field, and the dimension of each repeat field (that is, the number of field descriptors comprising a single occurrence of the repeat field).
10 2 Reserved
12 4 Flag word
  '80000000'x For boolean fields, this bit indicates the value of the field.
  '40000000'x This is an output-only field.
16 4 For repeat field headers (type='1000'x): Number of occurrences of repeat group (e.g. 50 group connections) Otherwise: Length of field data
20 4 Reserved
24 4 For repeat field headers (type='1000'x): number of elements (subfields) within a repeat group occurrence (For example, each group connection in the user profile consists of 15 subfields) Otherwise: offset to field data
28 16 Reserved
44 0 Start of next field descriptor, or if last field descriptor, start of field data