IBM Support

OA53355: NEW FUNCTION - USERKEY COMMON MIGRATION SUPPORT

A fix is available

Subscribe

You can track all active APARs for this component.

APAR status

  • Closed as new function.

Error description

  • New Function
    

Local fix

Problem summary

  • ****************************************************************
    * USERS AFFECTED:                                              *
    * All users running z/OS V2R1 and above                        *
    * that wish to identify user key common                        *
    * storage usage.                                               *
    ****************************************************************
    * PROBLEM DESCRIPTION:                                         *
    * User key common storage usage will not                       *
    * be supported after z/OS V2R3.  This                          *
    * APAR provides ways to identify user                          *
    * key common storage usage.                                    *
    ****************************************************************
    * RECOMMENDATION:                                              *
    * Apply the PTF.                                               *
    ****************************************************************
    The allocating, obtaining and 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 currently documented
    methods for identifying user key common storage usage may be
    too disruptive.  In addition, there is no assistance provided
    to identify user key common storage usage created via the
    CHANGKEY service.
    
    Additional ways to identify user key common storage usage
    are needed.
    

Problem conclusion

Temporary fix

Comments

  • This APAR provides additional methods for identifying user
    key common storage usage.  The methods include:
    
    - SMF Type 30 records were enhanced to identify jobs/steps
      that use user key common storage.
    
    - Allow installations to set a singular SLIP trap to catch
      ALL user key common storage usage.  Previously, different
      types of user key common storage usage require different
      SLIP traps.  This addresses the restriction that multiple
      PER type SLIPs could not be active at the same time.
      Previously, there was not a SLIP trap for user key common
      storage created via the CHANGKEY operation.
    
    - A new migration health check was created that will generate
      an exception message if user key common storage is used.
    
    In addition, the severity of existing health check,
    VSM_ALLOWUSERKEYCSA, has been raised to MED.
    
    Additional searchable keywords: SMFTYPE30 HCHECKER/K MSGIGVH114E
    
    For more details, see the following publication updates:
    
    GA32-0889-XX  z/OS Migration
    
    Update the 'Description' section of the 'Prepare for the
    removal of support for user key common areas' migration
    action:
    
      Description
    
      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.
    | In addition, setting the DIAGxx parmlib statement
    | VSM ALLOWUSERKEYCSA to YES will not be supported after
    | z/OS V2R3.  IBM strongly recommends specifying or
    | defaulting the ALLOWUSERKEYCSA statement to NO.
      :
      :
    
    Update the 'Steps to take' section of the 'Prepare for the
    removal of support for user key common areas' migration
    action:
    
      Steps to take
    
      1. If you are running CICS Transaction Server for z/OS,
    | ensure that you are running CTS V5.2 or later version.
    
    | 2. Check for usage of user key common areas. User key
    | common area usage include:
    | - Using the STORAGE, GETMAIN or CPOOL service to obtain
    |   common ECSA/CSA storage (subpool 227, 228, 231, 241)
    |   that specify a key of 8-15.
    | - Using the DSPSERV service to allocate a SCOPE=COMMON
    |   data space in a key of 8-15.
    | - Using the CHANGEKEY service to change the storage key
    |   of common storage to a key of 8-15.
    | To aid in finding all instances of user key common usage,
    | apply the PTF for APAR OA53355 on your production system.
    | This APAR will allow you to take one or more of the
    | following actions:
    |
    |   - Enable the following example SLIP trap to produce GTF
    |     trace records to help in identifying 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
    |
    |     Note: In the GTF trace record, register 2
    |     identifies the type of user key common
    |     storage usage:
    |
    |     1 = Attempt made to obtain user key CSA storage
    |         The 256-byte area included in the trace record due to
    |         "5R?,+FF" will include the 4-byte length at offset +4
    |         and the 1-byte subpool number at offset +21.
    |     2 = Attempt made to create a user key CADS
    |         The 8-byte area included in the trace record due to
    |         "0R?,+7" will contain the name of the data space.
    |     3 = Attempt made to change the key of common ESQA
    |         storage to a user key (via CHANGKEY)
    |
    |     When register 2 is not 3 (CHANGKEY), register 1 will
    |     contain the address of - the program attempting to use
    |     user key common storage
    |
    |   - Activate the ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM health
    |     check. This health check will issue an exception
    |     message when use of user key common storage is
    |     detected.  See the IBM Health Checker for z/OS User's
    |     Guide for more details.
    |
    |   - Ensure SMF Type 30 recording is active. The Storage
    |     and Paging section contains flags that indicate if
    |     user key common storage has been used.  See
    |     the System Management Facilities book for more
    |     information on the SMF30_UserKeyCsaUsage,
    |     SMF30_UserKeyCadsUsage and SMF30_UserKeyChangKeyUsage
    |     flags.
    |
    | 3. If the PTF for APAR OA53355 is not applied, you may take
    | one or more of the following actions to aid in finding all
    | 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 will fail.  The
    |   service receives one of the following abends:  B04-5C,
    |   B0A-5C, or B78-5C.
    |
    | - Specify ALLOWUSERKEYCADS(NO) in your DIAGxx parmlib.
    |   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
    |   will fail with a 01D-xx0015xx abend.
    |
    | - On z/OS v2r3 systems and above, specify
    |   NUCLABEL ENABLE(IARXLUK2) in your DIAGxx parmlib.
    |   Then, IPL a test system with the updated setting.
    |   Any software on your test system that attempts to
    |   use CHANGKEY to change subpool 247 or 248
    |   common storage to a user key (8-15) will fail
    |   with a 08F-1C abend.
    |
    | - Enable the following example SLIP trap to produce GTF
    |   trace records to help in identifying software that
    |   obtains user key CSA/ECSA storage:
    |
    |   SLIP SET,IF,A=TRACE,ID=UCSA,NUCEP=(IGVVSMG2,0,1),END
    |
    | - Enable the following example SLIP trap to produce GTF
    |   trace records to help in identifying software that
    |   allocates user key SCOPE=COMMON data spaces:
    |
    |   SLIP SET,IF,A=TRACE,ID=UCAD,NUCEP=(IAXDKUKY,0,1),END
    |
    | - Check for usage of the CHANGEKEY 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 support the
      storage not be 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 select units of work in select address spaces.
    
      - Use IARVSERV SHARE to share below the bar storage with
        select address spaces.
    
      - Use IARV64 GETSHARED to share above the bar storage with
        select address spaces.
    
      - Use z/OS UNIX shared memory to share below the bar or
        above the bar storage with select address spaces.
    
    
    SC23-6843-XX  IBM Health Checker for z/OS User's Guide
    
    Add the following new Health check:
    
    ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM
    Description:
        This check determines if any usage of user key common
        storage was detected on the system.
    Reason for check:
        Allowing programs to use user key common creates a
        security risk because common storage can then be
        modified by any unauthorized program. This check
        provides advanced warning of this potential security
        risk so the system programmer can take appropriate action.
    z/OS releases the check applies to:
        z/OS V2R1 and later.
    Parameters accepted:
        The following parameters are supported to control WTOs
        produced by exception messages when a new user key common
        storage usage attempt is detected:
        PARM('ALL')
            Exceptions should be issued if there are any user
            key common storage usage attempts made on this
            system since the last IPL.
        PARM('NEW(text value)')
            Exceptions should only be issued for user key common
            storage usage attempts that are detected after this
            parameter is set. The 'text value' is
            free-form and is not used by health check
            processing. It should contain text to help the user
            uniquely identify this particular parameter set.
        The following are examples of PARM specifications for
        ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM:
            PARM('NEW(yyyy/mm/dd hh:mm)')
            PARM('ALL')
    User override of IBM values:
        The following sample shows the defaults for customizable
        values for this check. Use this sample to make permanent
        check customizations in an HZSPRMxx parmlib member used
        at IBM Health Checker for z/OS startup. If you just want
        a one-time only update to the check defaults, omit the
        first line (ADDREPLACE POLICY) and use the UPDATE
        statement on a MODIFY hzsproc command. Note that using
        non-POLICY UPDATEs in HZSPRMxx can lead to unexpected
        results and is therefore not recommended.
        ADDREPLACE POLICY(policyname) STATEMENT(name)
        UPDATE
        CHECK(IBMVSM,ZOSMIGV2R3_NEXT_VSM_USERKEYCOMM),
        ACTIVE,
        INTERVAL(01:00),
        SEVERITY(HIGH),
        DATE('date_of_the_change'),
        REASON('Your reason for making the update.')
    Reference:
        See the 'Prepare for the removal of support for user key
        common areas' section in z/OS Migration.
    Messages:
        This check issues the following messages:
            IGVH113I
            IGVH114E
        See the IGVH messages in z/OS MVS System Messages, Vol 9
        (IGF-IWM).
    SECLABEL recommended for multilevel security users:
        SYSLOW - see z/OS Planning for Multilevel Security and the
        Common Criteria for information on using SECLABELs.
    
    
    SA38-0676-XX  z/OS MVS System Messages, Vol 9 (IGF-IWM)
    
    Add the following new IGVH messages:
    
    IGVH113I Use of user key common storage was not detected since
    auditstarttime
    
    IGVH114E Use of user key common storage detected since
    auditstarttime
    
    
    SA38-0667-XX  z/OS MVS System Management Facilities (SMF)
    
    Add the following new SMF Type 30 record fields in the
    Storage and Paging Section:
    Offsets  Name            Length  Format...
    178  B2  SMF30_RAXFLAGS  1       binary...
    
    Description
    Bit   Meaning
    0     When SMF30_USERKEYCOMMONAUDITENABLED is on,
          auditing of user key common storage usage attempts
          enabled for this step/job.
          SMF30_USERKEYCSAUSAGE, SMF30_USERKEYCADSUSAGE and
          SMF30_USERKEYCHANGKEYUSAGE are only applicable when
          this flag is on.
    1     When SMF30_USERKEYCSAUSAGE is on, attempts were made
          to obtain user key CSA storage for this step/job.
          This bit is only valid when
          SMF30_USERKEYCOMMONAUDITENABLED is on.
          Once this bit is set on for an interval record, this
          bit will also be set on for all subsequent interval
          records for this step.
          Once this bit is set on for a job interval or step-end
          record, this bit will also be set on for step-total
          and job-end records.
    2     When SMF30_USERKEYCADSUSAGE is on, attempts were made
          to create a user key CADS for this step/job.
          This bit is only valid when
          SMF30_USERKEYCOMMONAUDITENABLED is on.
          Once this bit is set on for an interval record, this
          bit will also be set on for all subsequent interval
          records for this step.
          Once this bit is set on for a job interval or step-end
          record, this bit will also be set on for step-total
          and job-end records.
    3     When SMF30_USERKEYCHANGKEYUSAGE is on, attempts were
          made to change the key of common ESQA storage to a user
          key (via CHANGKEY) for this step/job.
          This bit is only valid when
          SMF30_USERKEYCOMMONAUDITENABLED is on.
          Once this bit is set on for an interval record, this
          bit will also be set on for all subsequent interval
          records for this step.
          Once this bit is set on for a job interval or step-end
          record, this bit will also be set on for step-total
          and job-end records.
    
    
    GA32-0937-XX  z/OS MVS Data Areas Volume 3 (ITK - SCE)
    
    Add the following fields to the Structure RAX table:
      Offsets
      Dec   Hex   Type/Value   Len Name (Dim)   Description
      335  (14F)  BITSTRING     1  RAX_SMF30_SAPFLAGS
                  1... ....        RAX_USERKEYCOMMONAUDITENABLED
                                   "X'80'" Bit indicating that
                                   auditing of user key common
                                   storage usage attempts was
                                   enabled for this address
                                   space - Set by SMF
                  .1.. ....        RAX_USERKEYCSAUSAGE
                                   "X'40'" Bit indicating that
                                   attempts were made to obtain
                                   user key CSA storage for
                                   this address space
                  ..1. ....        RAX_USERKEYCADSUSAGE
                                   "X'20'" Bit indicating that
                                   attempts were made to create
                                   a user key CADS for
                                   this address space
                  ...1 ....        RAX_USERKEYCHANGKEYUSAGE
                                   "X'10'" Bit indicating that
                                   attempts were made to change
                                   the key of common ESQA storage
                                   to a user key (via CHANGKEY)
                                   for this address space
    
    Add the following fields to the Structure RCE table:
      Offsets
      Dec   Hex   Type/Value   Len Name (Dim)   Description
      542  (21E)  BITSTRING     1  RCEFLGS7
                  Bit definitions:
                  1... ....        RCE_USERKEYCOMMONUSAGE
                                   "X'80'" Indicates user key
                                   common storage usage
                                   attempts were made on this
                                   system since the health check
                                   requested a reset (if no
                                   reset was ever performed, it
                                   is since IPL)
                  .1.. ....        RCE_USERKEYCOMMONUSAGESINCEIPL
                                   "X'40'" Indicates user key
                                   common storage usage
                                   attempts were made on this
                                   system since the last IPL
    
     KEYWORDS: HCHECKER/K
    

APAR Information

  • APAR number

    OA53355

  • Reported component name

    ASM - AUX STOR

  • Reported component ID

    5752SC1CW

  • Reported release

    790

  • Status

    CLOSED UR1

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    YesSpecatt / New Function / Xsystem

  • Submitted date

    2017-07-10

  • Closed date

    2017-12-01

  • Last modified date

    2018-06-26

  • APAR is sysrouted FROM one or more of the following:

  • APAR is sysrouted TO one or more of the following:

    UA94604 UA94605 UA94606 UA94607 UA94608 UA94609

Modules/Macros

  • IEFTB728 IGVHCADC IEFTB726 IGVVSHJP IGVVSHEN IFAEASI  IGVHCHK1
    IARRCE   IGVHCMSG IFASMFR3 IAXXL    IAXDK    IGVVSMRT IARRAX
    IEFSD162 IEFTB721
    

Publications Referenced
SC236843XX SA380676XX SA380667XX GA320937XX GA320889XX

Fix information

  • Fixed component name

    VSM - VIRT STOR

  • Fixed component ID

    5752SC1CH

Applicable component levels

  • R79J PSY UA94609

       UP17/12/13 P F712  

  • R7BJ PSY UA94605

       UP17/12/13 P F712  

  • R7B0 PSY UA94604

       UP17/12/13 P F712  

  • R7A0 PSY UA94606

       UP17/12/13 P F712  

  • R790 PSY UA94607

       UP17/12/13 P F712  

  • R7AJ PSY UA94608

       UP17/12/13 P F712  

Fix is available

  • Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.



Document information

More support for: z/OS family

Software version: 790

Operating system(s): MVS, z/OS

Reference #: OA53355

Modified date: 26 June 2018