Prepare for the removal of support for user key common areas

Description

Allowing programs to obtain user key (8-15) common storage creates a security risk. Even if fetch protected, the storage can be modified or referenced by any unauthorized program from any address space. Therefore, it is recommended that you eliminate all use of user key common storage in z/OS V2R3. The allocating, obtaining, or changing common areas of virtual storage, such that the storage is in user key (8-15), will not be supported after z/OS V2R3.

The following DIAGxx parmlib statements will not be supported after z/OS V2R3:
VSM ALLOWUSERKEYCSA(YES)
This setting is not recommended for z/OS V2R3. Specify NO or accept the default of NO.
ALLOWUSERKEYCADS(YES)
This setting is the current default for z/OS V2R3. After z/OS V2R3, only the following setting will be allowed: ALLOWUSERKEYCADS(NO).
NUCLABEL ENABLE(IARXLUK2)
This setting is the current default for z/OS V2R3. After z/OS V2R3, only the following setting will be allowed: NUCLABEL DISABLE(IARXLUK2).

Table 1 provides more details about this migration action. Use this information to plan your changes to the system.

Table 1. Information about this migration action
Element or feature: BCP.
When change was introduced: V2R3.
Applies to migration from: z/OS V2R2 and z/OS V2R1.
Timing: Before the first IPL.
Is the migration action required? No, but recommended because this function will not be supported after z/OS V2R3.
Target system hardware requirements: None.
Target system software requirements: None.
Other system (coexistence or fallback) requirements: None.
Restrictions: None.
System impacts: See Steps to take.
Related IBM® Health Checker for z/OS® check: Use the following IBM Health Checker for z/OS checks:
  • VSM_ALLOWUSERKEYCSA to examine the setting of the ALLOWUSERKEYCSA option in the DIAGxx parmlib member.
  • ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM to detect usage of user key common storage.

Steps to take

  1. If you are running CICS Transaction Server (CTS) for z/OS, ensure that you are running CTS V5.2 or later.
  2. Check for the usage of user key common areas, such as the following uses:
    • STORAGE, GETMAIN, or CPOOL service is used to obtain common ECSA/CSA storage (subpool 227, 228, 231, 241) that specifies a key of 8-15.
    • DSPSERV service is used to allocate a SCOPE=COMMON data space in a key of 8-15.
    • CHANGKEY service is used to change the storage key of common storage to a key of 8-15.
    For help with finding instances of user key common usage, apply the PTFs for APARs OA53355 and OA56180 to your production system. Doing so allows you to take one or more of the following actions:
    • Set the following example SLIP trap, which produces GTF trace records that identify software that uses user key common storage: 
      SLIP SET,IF,A=TRACE,ID=UKEY,NUCEP=(IARXLUK4,0,1),
TRDATA=(STD,REGS,0R?,+7,5R?,+FF),END
      In the GTF trace record, register 2 identifies the type of user key common storage usage, as shown in Table 2. When register 2 is set to 1, 2, or 4, register 1 contains the address of the program that attempted to use user key common storage.
      Table 2. Register 2 identifies the type of user key common storage usage
      Register 2 contents Meaning
      1 Caller attempted to obtain user key CSA storage. The 256-byte area included in the trace record due to "5R?,+FF" includes the 4-byte length at offset +4 and the 1-byte subpool number at offset +21.
      2 Caller attempted to create a user key CADS. The 8-byte area included in the trace record due to "0R?,+7" contains the name of the data space.
      3 Caller attempted to change the key of common ESQA storage to a user key (through CHANGKEY).
      4 Caller attempted to fault on user key CSA storage when a RUCSA is defined.
      5 Caller attempted to release user key CSA storage.
      7 Caller attempted to change the access of user key CSA (through IARVSERV CHANGEACCESS) when a RUCSA is defined.
      8 Caller attempted to protect or unprotect user key CSA (through PGSER PROTECT or UNPROTECT) when a RUCSA is defined.
    • Activate the ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM health check. This health check issues an exception message when it detects usage of user key common storage.
    • Ensure that SMF Type 30 recording is active. The Storage and Paging section contains flags that indicate whether user key common storage is used. See z/OS MVS System Management Facilities (SMF) for information about the related flags:
      • SMF30_UserKeyCsaUsage
      • SMF30_UserKeyCadsUsage
      • SMF30_UserKeyChangKeyUsage
      • SMF30_UserKeyRuCsaUsage
  3. If the PTF for APAR OA53355 is not applied, you can take one or more of the following actions to find instances of user key common usage:
    • Set the DIAGxx parmlib statement VSM ALLOWUSERKEYCSA to NO, which is the default. Then, IPL a test system with the updated setting. Any software on your test system that attempts to obtain user key CSA/ECSA by using the GETMAIN, STORAGE, or CPOOL service fails with one of the following abends: B04-5C, B0A-5C, or B78-5C.
    • Specify ALLOWUSERKEYCADS(NO) in your DIAGxx parmlib member. Then, IPL a test system with the updated setting. Any software on your test system that attempts to obtain a user key (8-15) SCOPE=COMMON data space fails with a 01D-xx0015xx abend.
    • On z/OS V2R3 systems, specify NUCLABEL ENABLE(IARXLUK2) in your DIAGxx parmlib member. Then, IPL a test system with the updated setting. Any software on your test system that attempts to use the CHANGKEY service to change subpool 247 or 248 common storage to a user key (8-15) fails with a 08F-1C abend.
    • To help identify software that might be affected, set the following example SLIP traps to produce GTF trace records. Only one non-ignore PER SLIP trap can be enabled on a system at one time.
      1. To identify programs that obtain user key CSA/ECSA storage, set a SLIP trap such as the following:
        SLIP SET,IF,A=TRACE,ID=UCSA,NUCEP=(IGVVSMG2,0,1),END
      2. To identify programs that allocate user key SCOPE=COMMON data spaces, set a SLIP trap such as the following: 
        SLIP SET,IF,A=TRACE,ID=UCAD,NUCEP=(IAXDKUKY,0,1),END
    • Check for usage of the CHANGKEY service to change the storage key of common storage to a key of 8-15.
  4. Change the affected software to support having the user key common areas of virtual storage areas protected in a system key. Or, change the affected software to use storage that is not common to all address spaces. Some alternatives for sharing storage (instead of having storage common to all address spaces) include the following options:
    • Use a SCOPE=ALL data space to share data space storage with specific units of work in specific address spaces.
    • Use IARVSERV SHARE to share below-the-bar storage with specific address spaces.
    • Use IARV64 GETSHARED to share above-the-bar storage with specific address spaces.
    • Use z/OS UNIX shared memory to share below-the-bar or above-the-bar storage with specific address spaces.
  5. For some z/OS installations, it might not be possible to immediately update all of the affected software, or more assistance might be required to identify programs that reference user key CSA storage. In these cases, consider using the more secure restricted use common service area (RUCSA) provided by the PTF for APAR OA56180. However, IBM still recommends the elimination of all user key common storage. For more information about RUCSA and migrating to it, see z/OS MVS Initialization and Tuning Guide.

Reference information

For more information, see the following references: