Coding appropriate CVKEY values based on the Z/OS AllowUserKeyCsa parameter

Document ID : KB000049467
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

IBM Z/OS releases 1.8 and higher include an AllowUserKeyCsa parameter. The values which are allowable for CVKEY depend on the settings for this parameter. Since the Program Properties table (PPT) also indicates the protect key chosen for the CV, it is also impacted by this.

Solution:

On Z/OS r1.8 IBM introduced a new parameter (Allowuserkeycsa) which impacts allocation of storage from CSA subpools, depending on the key in which the CV is running. On Z/OS r1.9, IBM changed the default setting of that parameter; this is documented in APAR QI82743. This parameter introduces the need to consider what value is specified for the CVKEY of the #SVCOPT Macro. The value specified in the Program Properties table (PPT) to indicate the IDMS protect key is also impacted by this, since it must agree with the CVKEY value.

The CA IDMS Installation Guide contains a line that recommends using CVKeys 10-15; this was actually written before the Allowuserkeycsa parameter changes were introduced by IBM, and unfortunately that section of the manual wasn't updated to discuss the impact of the Allowuserkeycsa parameter. This paragraph, in the chapter "Configuring CA IDMS", section "Secured CA IDMS System on Z/OS", subsection 'CVKEY Parameter", begins as follows:

"Programs that execute with a key of less than 8 are privileged in z/OS. CA IDMS does not require these privileges; a key in the range of 10 to 15 is recommended. CA IDMS operates successfully in any key other than 9, which is due to a z/OS limitation in IOS. Specifying a system key (0 through 7) is not advantageous; however, it can be useful for preventing batch or V=R jobs from directly viewing or altering the ECSA storage used by CA IDMS."

Determining the appropriate value for CVKEY now depends on the value selected for the Z/OS AllowUserKeyCsa parameter. If your LPA specifies AllowUserKeyCsa(YES), then any "USER" type CVKEY value is OK, except for 9, which means you could run with 8 or 10-15 as the primary protect key for IDMS. However, if your Z/OS environment specifies AllowUserKeyCsa(NO), then the IDMS Central Version (CV) cannot run in a USER key. That means you can't use any of the values 8 - 15, and must choose a value in the range of 1 - 7 instead. In that case we recommend using key 4. The LPAR in which we run our test CVs specifies AllowUserKeyCsa(NO) so our CVs run in key 4.

The CA IDMS Installation Guide has also caused some confusion regarding PPT values. The chapter "Configuring CA IDMS", section "Secured CA IDMS System on Z/OS", includes a statement reading
"Update the Program Properties table (PPT) to include the protect key chosen for CA IDMS."

This is entirely accurate and should always be the case. However, it is followed in the next section by the statement above which states that the CVKEY "in the range of 10 to 15 is recommended." This has led some users to infer that the PPT value should always be in the range of 10 to 15. Yet there is another statement regarding PPT values in Chapter 7 "Post-Configuration Tasks", in the section "Z/OS Environment", that reads:

"The PPT must be updated to indicate RHDCOMVS (the startup module) should run in key 4 or any other system key of your choice in the range of 1 to 7."

This latter reference in only true in the circumstance noted above, where the CVKEY value is also in this range, which is when the AllowUserKeyCsa(NO) is specified. The truest statement is the one quoted at the beginning of this paragraph that each site should "Update the Program Properties table (PPT) to include the protect key chosen for CA IDMS."

To ensure all of the parameters are correctly coded and in agreement, then, each Z/OS CA IDMS site should:

  1. Determine whether to run with AllowUserKeyCsa(YES) or AllowUserKeyCsa(NO).

  2. Choose an appropriate value for the CVKEY value in the #SVCOPT macro based on the AllowUserKeyCsa parameter setting;

    1. If AllowUserKeyCsa(YES) is specified, then use a value in the range of 10 to 15 as the CVKEY.

    2. If AllowUserKeyCsa(NO) is specified, then use a value in the range of 1 to 7as the CVKEY; we recommend 4.

  3. Once the primary protect key for IDMS (CVKEY) is chosen, update the Program Properties table (PPT) to include that value.