Debugging Authority Failures, Part 3

November 2, 2011 Patrick Botz

Authority failures are the result of attempts (i.e., actions) to access objects to which a user profile is not authorized. Several IBM i features, such as job logs and QHIST, contain some authority failure information. However, the system audit journal has all the information you need, and the OS provides easy-to-use tools to help you quickly find it. These tools are the audit configuration system values, the CPYAUDJRNE command, and the STRSQL command.

Audit System Values

To begin auditing authority failures, configure three system values: QAUDCTL, QAUDLVL, and QAUDLVL2. QAUDCTL is an on/off switch for auditing specific objects, specific user profiles, or specific actions. The QAUDLVL and QAUDLVL2 system values are used to define one or more specific actions to audit. QAUDLVL allows for up to 16 different actions to be specified. If you need to specify more, the additional values are defined in QAUDLVL2. In practice, few shops need to use QAUDLVL2. To turn on action auditing for authority failures set QAUDCTL to *AUDLVL and add *AUTFAIL to QAUDLVL (or QAUDLVL2 if necessary).

If you haven’t previously turned on auditing on your system, you’ll have to create a journal receiver and journal before you can set the QAUDCTL system value.

The most convenient way to accomplish all of this is through the Display Security Auditing (DSPSECAUD) and Change Security Auditing (CHGSECAUD) commands. DSPSECAUD shows all of the relevant information for system auditing including the QAUDCTL, QAUDLVL, QAUDLVL2, and the journal and receiver currently being used. CHGSECAUD allows you to easily add to, remove from, or change the current settings from one screen.

Once you have turned on auditing for authority failures, you’ll always have all the information you need to debug authority failures at your fingertips.

CPYAUDJRNE Command

Now you need to extract the audit failure information. IBM makes this easy as well, via the CPYAUDJRNE (Copy Audit Journal Entry) command.

CPYAUDJRNE lets you specify myriad options, but the defaults happen to be very useful for finding information for debugging authority failures. The options you can choose (and their defaults) are:

Entry type (AF).
Output file name prefix (QTEMP/QAUDIT)–The full name of the output file is the prefix concatenated with the entry type (e.g., QTEMP/QAUDTAF).
Output file member options (*FIRST, *REPLACE).
User profile (*ALL)–This parameter allows you to select only those entries related to the specified user profile.
Starting and ending journal receiver to search (*CURRENT)–Audit journal receivers fill up over time. When a receiver fills, the system detaches it and creates a new one–assuming you have the system manage the journal receivers. Otherwise, you have to manage this yourself. If you know that an authority failure occurred recently, you can specify *CURCHAIN. The more receivers you search the more entries it will have to sift through to find matches.
Starting date and time (*FIRST).
Ending date and time (*LAST)–Starting and ending dates/times minimize the number of entries that are copied to the outfile.

I generally use all of the defaults except for the JRNRCV parameter, where I usually specify *CURCHAIN for the starting journal receiver. This ensures I find all of the authority failure entries still available on the system. If the error occurred within the last few minutes, you can use the default of (*CURRENT) and the command may run a little more quickly. If you’re concerned about the number of journal receivers and the time it will take to complete the command, specify a subset of the available receivers.

One way to limit the number of AF entries you capture from the audit journal is to only retrieve entries associated with a specific user profile. Another way is to specify a relatively small date/time window.

Now you have a subset of audit entries. Most likely it contains the authority failure associated with the problem that was reported.

STRSQL

Now it’s time to analyze the audit records. I like to use STRSQL to view the entries I just copied. It helps me analyze the entries and to find and display only the fields in which I’m interested.

The layout of all audit entry types is defined in Appendix F of the Security Reference manual. Typically, I peruse the information for the entry I’m looking at in order to get a handle on what information is available and how to read the entry.

On the STRSQL command line, I typically enter “select * from qtemp/qauditaf”. This gives me information about how many total records are available, and if an authority issue is systemwide or if it is specific to a user or object.

From the previous articles (see “Related Stories” below), we know that we need to find the following information:

Object library, name, and type to which access was denied–With this information you use the EDTOBJAUT command to see who has been granted what kind of authority to the object.
User profile to which the access was denied–This is often not the same as the “Job User ID”. Do not assume that the job user is the same as the user who was denied access to the object.
Program library and name that was attempting to access the object at the time the failure occurred.

Here’s an example of select statement that gets the necessary information for an authorization failure for QSYS.LIB objects and IFS directories or files:

SELECT AFENTT, AFPGM, AFPGMLIB, AFPNAM,
       AFPLIB, AFVIOL, AFONAM, AFOLIB,
       AFOTYP, AFUSEP, AFPNLN, AFAPIN,
       AFPNM
  FROM qtemp/qauditaf

This produces output like the following:

                                  Display Data
                                              Data width . . . . . . :    5131
 Position to line  . . . . .              Shift to column  . . . . . .
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
 Type  Program     Program     Program     Program     Violation  Object      Li
       name        library     name        library     type       name        na

  AF   QCMD        QSYS                                    A      BOTZLIB     QS
  AF   QCMD        QSYS                                    A      *N          *N
  AF   QCMD        QSYS                                    A      *N          *N
********  End of data  ********

Here are the field descriptions:

• The first field, “Type” (field name=AFENTT, Authority Failure Entry Type), is redundant. I include it just to remind me of the type of entry I’m analyzing.

• The next two fields are “Program name” and “Program library” (field names AFPGM, AFPGMLIB respectively). This is the name of the program that caused the journal entry to be written. It is not necessarily the program in which the authority failure occurred.

• The second “Program name” and “Program library” headers (field names AFPNAM and AFPLIB) are the name of the library and program that encountered the failure.

NOTE: As you can see, for violation type A, only one of these may be provided. This indicates that it was probably a system CL command running when the error happened. The error was signaled to QCMD and QCMD caused the audit entry to be written.

The combination of these fields represents item number 3 in the description of the information you need to debug authority failures.

• Violation type field (AFVOIL) is a one character code that provides more detail on the exact nature of the authority failure. The code definitions are found in the layout information for the AF record in Appendix F of the Security Reference manual. Looking there, we find that “A” means “Not authorized to object”. This is what we were expecting.

NOTE: Depending on what’s happening on a system, it can be useful to limit the amount of entries by using a “where AFVIOL=’A'” clause in your SQL statement.

• The last full field on this screen is Object name (field name AFONAM). This field provides the name of the object on which the authority failure occurred. This field, combined with fields on the next screen, represents item number 1 of the information you need to debug authority failures.

Positioning to column 78 shows this:

                                  Display Data
                                              Data width . . . . . . :    5131
 Position to line  . . . . .              Shift to column  . . . . . .   78
 ..8....+....9....+...10....+...11....+...12....+...13....+...14....+...15....+.
 Library     Object    User        Path     Absolute   Path
 name        type      profile     name     path       name
                                   length   indicator
 QSYS        *LIB      BOTZTEST         0
 *N          *DIR      BOTZTEST        12       Y      /home/pbotz1
 *N          *DIR      BOTZTEST        12       Y      /home/pbotz1
 *N          *DIR      QSRVAGT         20       Y      /QIBM/UserData/OS400
 ********  End of data  ********

More field descriptions:

• Library name and object type (field names AFOLIB and AFOTYP) complete the required information described in item number 1 above. The first entry indicates that the object that incurred the authority failure was a library name BOTZTEST. Because it is a library, its library is QSYS.

The next two entries are curious though. Instead of names for the object name and library they show “*N” for these fields. *N means that the failing object is something other than a QSYS.LIB object. The type field value of “*DIR” confirms this. *N also indicates that the path name of the object is in the path name and/or relative path name fields of this entry.

• The final required piece of information, item number 2 above, is the User profile field (field name AFUSEP). This field is in the entry specific information part of the AF record. It indicates the user profile that did not have the required authority.

NOTE: Do not rely on the job name user field. It is not necessarily the user profile that attempted the unauthorized access.

The rest of the fields in the entry help you determine the full path name of the failing object–assuming it is not a QSYS.LIB object.

• Path name length (field name AFPNLN) tells you the length of the pathname of the failing object.

NOTE: There are several fields related to CCSID, region, and language that I don’t usually bother with unless I know the machine is using NLS capabilities. I use the path name length field as a sanity check against what I see in the path name field itself. It can also be useful if the path name is in a different CCSID.

• Absolute path indicator (field name AFAPIN) shows whether or not the value in the path name field is the full path name or just the object name itself. If this field is set to N, then you have to look at the relative path name to determine the path name to the object.

In some instances, only an object ID (fields not selected) for the object, or the relative path is available. In these cases no information appears in the Path name field. You have to pass the object ID to an IFS API to return the full pathname of the object. Luckily, this is not the usual occurrence.

• I always put the path name field (field name AFPNAM) as the last field in the select statement. Path name is a 5,002-character length field! You have to scroll or position 5,002 characters beyond the start of the path name to see any fields that appear after the path name field in the select statement.

For all entries in which the object name and library name fields are *N, you’ll be looking in this area of the AF audit record to determine the name of the failing object.

So, there you have it. Armed with the information from the AF audit record, you can determine what user profile was unauthorized and the object to which the user profile was not authorized. Using the failing object name library and type as parameters to EDTOBJAUT, you can determine what authority, if any, the profile has to the object. With all of that information you can make a reasonable and logical change to your access control scheme, whether that means adding the user to a group, granting the profile or a group sufficient private authority, or using adopted authority on a program.

Happy debugging!

Patrick Botz is the principal consultant and founder of Botz & Associates Inc. He is also president of Valid Technologies, LLC, a biometric middleware ISV. Pat spent nearly 20 years working at IBM in various security roles including lead IBM i security architect, IBM eServer security team, and the head of IBM Lab Services Security Consulting practice. Check out his Website at www.botzandassociates.com. Send your questions or comments for Patrick to Ted Holt via the IT Jungle Contact page.