Planning Considerations for enabling KDFAES

Create a backup copy of your RACF database

Creating a backup of the RACF database is recommended whenever significant changes are being made to RACF and the RACF database.

Apply OA43998 and OA43999 to all systems lower than z/OS V2R2 that share the RACF database

Make sure that the service is applied on all sharing systems that are lower than z/OS V2R2, and that all the ++HOLD documentation has been reviewed.

Apply service to other affected products

Informational APAR II14765 contains pertinent information (e.g. restrictions) for other software products related to this support.

Determine if programs you have written are affected

Check programs you have written to ensure that they can tolerate the new function.

Certain types of applications are affected when the new algorithm is activated. Any application that authenticates a user or stores into the RACF database using clear text is not affected.

Applications that are affected are those that have dependencies on the DES format of the PASSWORD field in the RACF database. For example, if the password field is extracted (using ICHEINTY or RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT) and compared against a password that the application has encrypted itself (possibly by using RACROUTE REQUEST=EXTRACT,TYPE=ENCRYPT), this no longer works when the password on the RACF database is encrypted under KDFAES.

Another example is an application that passes a pre-encrypted password to RACROUTE REQUEST=VERIFY/X with ENCRYPT=NO. If the application supplies a current password extracted from the current password field, it fails when the password on the RACF database is encrypted under KDFAES. If the application supplies a new password that is encrypted using RACROUTE, this might not work after KDFAES is activated. The encryption method is specified on RACROUTE REQUEST=EXTRACT,TYPE=ENCRYPT,ENCRYPT=(data-addr,method). If the method specified is DES, this continues to work. If the method specified is STDDES or HASH, this does not work. If the method is INST, and there is no ICHDEX01 exit active, or the exit directs RACF to use DES, then this continues to work. However, if the exit directs RACF to use the masking algorithm, or if the exit performs its own encryption algorithm, this does not work.

Any application that copies a password or manages the password history is affected when the password is encrypted using KDFAES. That application then requires awareness of the active encryption algorithm and must take into account new password extension fields that are used for a KDFAES password.

RACF exit considerations

Determine if the new function affects RACF exits, if present on your system.

ICHDEX01 – Password authentication exit

The ICHDEX01 exit can be used to implement an encryption algorithm, or to instruct RACF to use DES or masking. These three algorithms are collectively referred to as “legacy”, to differentiate them from KDFAES. If there is no ICHDEX01 exit, RACF uses DES while evaluating passwords. After KDFAES is activated, RACF continues to call ICHDEX01 to evaluate a legacy password, but will no longer honor masking. When a password is changed under KDFAES, ICHDEX01 is no longer called for that password.

The considerations for activating KDFAES depend on the legacy algorithm currently active.

DES

If you have no ICHDEX01 exit, or your ICHDEX01 exit directs RACF to use the DES algorithm (by setting return code 8), then there are no issues with activating KDFAES, or performing a KDFAES conversion.

Installation-defined encryption method

If you have an ICHDEX01 exit that performs its own encryption algorithm, it needs to stay active until all passwords have been changed under KDFAES and until all non-KDFAES history entries have been replaced in the history. Do not perform a KDFAES conversion. The conversion function assumes that the input password hash is created with DES. If you do perform a conversion, a user is no longer able to log on with their existing password, and an administrative password change is required. Also, history entries are not usable. (A user is able to reuse any installation-encrypted password value that is contained in history).

You can determine when no more legacy passwords, phrases, and history values exist by using fields unloaded by IRRDBU00.

Masking

Masking is only active for encrypting passwords when you have an ICHDEX01 exit that sets return code 4. Since masking is never used when KDFAES is activated, there is more work to do on your part. Do not perform a KDFAES conversion. The conversion function assumes that the input password hash is created with DES. If you do perform a conversion, a user can no longer log on with their existing password, and an administrative password change is required. Instead, either:

• Convert to DES before activating KDFAES. This would entail changing ICHDEX01 to set a return code of 16, which causes RACF to encrypt new passwords using DES, and to try masking during evaluation if the DES evaluation fails. The password expiration function can be used to force users to change their password at their next log on attempt, however, this does not address existing history entries. It might not be easy to know when all user passwords have changed, as RACF provides no way to differentiate a masked password from a DES password on the RACF database.
• Implement a bulk password change on a test system, and sacrifice your history entries. Follow these steps:
  1. Make a copy of the your RACF database.
  2. Activate this copy on a test system.
  3. Activate KDFAES on the test system.
  4. Perform a bulk password change, notifying users of their pending new password.
  5. Activate this copy on your production system.
  6. Remove your ICHDEX01 exit

Attention: This results in unusable history entries (a user can reuse any previously masked password value contained in history).

ICHPWX01 – New password exit

The ICHPWXP parameter list contains the address to a password history structure (the PWXPWHST field). This parameter is passed to the exit by RACROUTE REQUEST=VERIFY/X and the PASSWORD command. When KDFAES is enabled, the PWXPWHST field is always 0, even if SETROPTS PASSWORD(HISTORY(n)) is active.

ICHPWX11 – New password phrase exit

When KDFAES is not active, the ICHPWX11 exit must approve a password phrase value between 9 and 13 characters, inclusive. In the absence of an ICHPWX11 exit, RACF rejects any password phrase less than 14 characters in length. A REXX-based sample exit is provided in SYS1.SAMPLIB.

When KDFAES is active, RACF allows a password phrase value of 9 characters or higher without an ICHPWX11 exit being active. You can remove the ICHPWX11 exit after enabling KDFAES if the only purpose of the exit is to allow a password phrase less than 14 characters.

If you use the sample exit for the additional checking it provides, and the version have installed is from a release lower than z/OS V2R2, note that the IRRPHREX exec requires a change if you plan to enable the new encryption algorithm and take advantage of the 9-character minimum password phrase length. The exit, as written, fails a password phrase less than 14 characters in length.

RACF download considerations

If you are using RACF downloads, determine if they are affected. The following downloads are available on the RACF web site at: http://www-03.ibm.com/systems/z/os/zos/features/racf/goodies.html.

CUTPWHIS

This is a utility that removes extraneous passwords from the RACF password history. This function is now provided by the PWCLEAN keyword of the ALTUSER command.

Attention: Continued use of CUTPWHIS after activating the new encryption algorithm results in damaged password history and allows users to reuse password values.

PWDCOPY

This is a utility that copies passwords from one RACF database to another RACF database. Make sure you are using the updated version.

Attention: Continued use of the old version of PWDCOPY after activating the new encryption algorithm results in users being unable to log on on the target system of the copy.

Performance and space considerations

CPU consumption

The new encryption algorithm intentionally uses a higher amount of CPU than DES. It can be difficult to predict the effect this algorithm has on user response time and overall system performance, as it depends on the frequency of password evaluations.

This also affects password and password phrase changes, especially when history is active. Beyond the encryption that is required to verify the current value, the new value must also be encrypted. When history is active, the new value needs to be encrypted separately against each KDFAES history value to perform the comparison. If you have a high history value, and your users all tend to change their passwords on the same day, consider using the EXPIRED operand of the ALTUSER command to evenly distribute password expiration dates among your user population. Also, consider using the PWCLEAN function of ALTUSER if you have lowered your history value in the past.

Attention: IBM strongly recommends that you implement RACF ACEE caching using the IRRACEE class in VLF. For more information, see ACEEs and VLF considerations. For information on VLF, see z/OS MVS Programming: Authorized Assembler Services Guide.

RACF database performance and space utilization

Passwords, password phrases, and history encrypted under KDFAES occupies more space in USER profiles than they do under DES. A password extension field is defined in the RACF database templates for each of these entities to contain the additional information that does not fit within the current field. For password and password phrase history, a parallel field contains the extension information, and requires a corresponding set of generation numbers by which to index the elements. The size of a password, password history entry, and password phrase history entry increases by approximately 40 bytes. The current password phrase field is variable length. Under KDFAES, a password phrase is stored in the same manner as a password. Using your SETROPTS PASSWORD(HISTORY(n)) value, you can determine approximately how much more space is required. Ensure that your RACF database contains enough unused space to accommodate this, and increase the size of your database if necessary.

As passwords and password phrases change over time, and a user's profile grows in size, it might need to be split across data blocks in the RACF database. When this happens, references to this profile require additional I/O. IRRUT400 can be used to reorganize databases to bring the blocks back within close proximity of each other, including the index block that references them.

Consider performing a KDFAES conversion (for passwords and password history) up front to get the user profiles to their maximum size, and then perform a reorganization. Keep in mind, however, that conversion does not affect password phrases. If you use password phrases, the profile grows slowly over time, as they are changed.

Test the change

After activating KDFAES and changing your password, you can then log on to all applications that provide an authentication dialog. Then, change your password or password phrase with all such applications and verify that you can authenticate with the new value.

Using test workloads that are indicative of your production workloads, you can estimate performance impacts. You can consider performing a KDFAES conversion to ensure that your database can accommodate the extra space utilization. You could also use IRRUT400 to reorganize the database, and then activate that copy.