PH44820: MQ Z/OS:CSQ0216E AFTER CERTIFICATE RENEW

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• When there are messages that were put with an old certificate,
  they are not able to be read with the new certificate after the
  AMS refresh and issued following message:
  CSQ0216E CSQ1 CSQ0CGET Message unprotection failed,
  return code 8, reason 03353033
  CSQ0217E CSQ1 CSQ0CGET Failed to process object
  'pkcs7 enveloped data message
  
  Recreate steps:
  Renew the certificate {extending the expiration date for
  another year}:
  RACDCERT ID(U024001) LIST(LABEL('U024001 Certificate'))
  RACDCERT GENREQ(LABEL('U024001 Certificate')) ID(U024001) -
    DSN('USER01.CACERT1')
  RACDCERT GENCERT('USER01.CACERT1') ID(U024001) -
   SIGNWITH(CERTAUTH LABEL('AMS Bank1 CA Certificate'))
  RACDCERT ID(U024001) ALTER (LABEL('U024001 Certificate')) TRUST
  
  
  1] workload running
  2] renew certificates extending the expiration date for another
  year
  3] issue 'refresh security type(ssl)'
  4] workload continues to run without any issues
  5] start and restart workload and it continues to run
  successfully
  6] refresh AMS security with the qmgr running this workload 'F
  CSQxAMSM,REFRESH ALL'
  Now the clients are failing with the following errors -- since
  the workload is browsing messages on the queue. It's failing
  when accessing messages that were put using the 'certificate'
  prior to extending the expiration date.
  "CSQ0216E CSQ1 CSQ0CGET Message unprotection failed,
  return code 8, reason 03353033
  CSQ0217E CSQ1 CSQ0CGET Failed to process object
  'pkcs7 enveloped data message'  "
  7] stopped the workload and cleared all messages on the queue
  8] successfully restarted the workload without any issues
  {messages are successfully put / browsed from the queue}
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of IBM MQ for z/OS Version 9       *
  *                 Release 1 Modification 0,                    *
  *                 Release 2 Modification 0, and                *
  *                 Release 3 Modification 0.                    *
  ****************************************************************
  * PROBLEM DESCRIPTION: MQGET fails with MQCC_ERROR (2) and     *
  *                      MQRC_SECURITY_ERROR (2063) when getting *
  *                      messages protected prior to the renewal *
  *                      of the certificate that was used to     *
  *                      protect them.                           *
  *                      The error is accompanied by messages    *
  *                      CSQ0216E and CSQ0217E, reporting the    *
  *                      failure of CSQ0CGET to unprotect the    *
  *                      message with return code 8, reason      *
  *                      03353033                                *
  ****************************************************************
  Messages on a queue protected by an integrity or confidentiality
  policy contain information that is used to identify the correct
  certificate containing the private key necessary to decrypt it.
  When a certificate is renewed, the information in messages
  protected prior to the renewal will no longer identify the
  renewed certificate, causing decryption to fail.
  
  If the user's default certificate is changed to the old
  certificate to resolve this, messages protected since the
  certificate renewal cannot be decrypted.
  
  Workaround
  When renewing a certificate ensure all messages protected
  using that certificate have been removed from the queue and
  processed prior to updating the getter's default certificate
  in the getter and AMS address space keyrings, and refreshing
  the AMS certificate cache.
  

Problem conclusion

• Unprotect processing for integrity and confidentiality
  protected messages is changed to consider any trusted
  certificates in the getting user's keyring that match one of the
  recipient DN's specified in the queue's policy, in addition to
  the user's default certificate in that keyring.
  When renewing certificates, this allows messages that were
  protected using either the old or new certificate to be
  unprotected successfully.
  
  
  The following changes are made to the IBM MQ for z/OS Knowledge
  Centre:
  
  The following changes are made to the IBM MQ Knowledge Centre:
  
  https://www.ibm.com/docs/en/ibm-mq/9.3?
                                  topic=zos-use-saf-key-rings-ams
  "Use of SAF key rings with AMS on z/OS"
  
  Add a new subpage "Replacing certificates"
  The new page contains:
  "
  When a certificate is renewed or replaced (for example, when the
  existing certificate is approaching its expiry date), it is not
  always possible to unprotect existing messages that are already
  on queues protected by Confidentiality or Privacy policies.
  This can occur when
   - the certificate was renewed with the same private key, and
     the reissued certificate has replaced the original
     certificate
   - the certificate was rekeyed with a new private key and the
     RACDCERT ROLLOVER command has deleted the original private
     key
  
  Prior to PH44820, when the new certificate is connected to the
  user's keyring as the default certificate, it is no longer
  possible to decrypt messages encrypted using the old
  certificate.
  When PH44820 is applied messages will be decrypted provided the
  necessary certificate is connected to the user's keyring - it is
  no longer required to be connected as the default. This allows
  messages already on the queue when the new certificate is
  connected to be successfully decrypted.
  
  The following example shows how a new certificate can be
  generated based on the existing certificate when PH44820 is
  applied:
  - A new certificate is created based on the existing
    certificate, with new public/private key pair
  - The new certificate is signed by the issuing authority
  - The old certificate's public key is removed from the AMS
    address space's keyring, and the new certificate's public key
    is added.
  - The new certificate and private key is added to the user's
    keyring, in addition to the old certificate
  <code block>
  RACDCERT ID(user1) REKEY(LABEL('user1'))          -
           WITHLABEL('user1new')
  
  RACDCERT GENREQ(LABEL('user1new')) ID(user1)      -
           DSN(output_data_set_name)
  
  RACDCERT GENCERT(output_data_set_name) ID(user1)  -
           SIGNWITH(CERTAUTH LABEL('AMSCA'))
  
  RACDCERT ID(user1) ALTER (LABEL('user1new'))      -
           TRUST
  
  RACDCERT ID(WMQAMSD) REMOVE(ID(user1)             -
           LABEL('user1')                           -
           RING(drq.ams.keyring) )
  
  RACDCERT ID(WMQAMSD) CONNECT(ID(user1)            -
           LABEL('user1new') USAGE(SITE)            -
           RING(drq.ams.keyring) )
  
  RACDCERT ID(user1) CONNECT(ID(user1)              -
           LABEL('user1new') USAGE(PERSONAL)        -
           RING(drq.ams.keyring) DEFAULT )
  </code block>
  
  For more information about certificates, labels, and the
  RACDCERT command, see z/OS: Security Server RACF Command
  Language Reference and z/OS: Security Server RACF Security
  Administrator's
  Guide.
  "
  
  https://www.ibm.com/docs/en/ibm-mq/9.3?
                                  topic=zos-use-saf-key-rings-ams
  "Use of SAF key rings with AMS on z/OS"
  
  Change:
  "
  The private key used for signing and decryption can have any
  label but must be connected as the default certificate.
  "
  to
  "
  The private key used for signing can have any label but must be
  connected as the default certificate.
  Prior to PH44820 the private key used for decryption can have
  any label but must be connected as the default certificate.
  When PH44820 is applied the private key(s) used for decryption
  can have any label, and must be connected to the key ring, but
  are no longer required to be connected as the default
  certificate
  "
  
  
  https://www.ibm.com/docs/en/ibm-mq/9.3?
                   topic=zos-connecting-certificates-key-rings-ams
  
  "Connecting the certificates to the key rings for AMS on z/OS"
  Change:
  "
  The certificate containing the private key used for decryption
  must be connected to the user's key ring as the default
  certificate.
  "
  to
  "
  Prior to PH44820, the certificate containing the private key
  used for decryption must be connected to the user's key ring as
  the default certificate.
  When PH44820 is applied, any certificates containing the private
  key(s) used for decryption must be connected to the user's key
  ring, however they are no longer required to be connected as the
  default certificate.
  "
  

Temporary fix

Comments

APAR Information

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

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

  UI93812 UI93813 UI93814

Modules/Macros

• CSQ0DLCF CSQ0DLCL CSQ0DPRI CSQ0DPRT CSQ0DUNP CSQ0STAT CSQ0STRT
  CSQIRECP
  

Fix information

• Fixed component name

  IBM MQ Z/OS V9

• Fixed component ID

  5655MQ900

Applicable component levels

• R100 PSY UI93814

     UP23/10/10 P F310

• R200 PSY UI93813

     UP23/10/10 P F310

• R300 PSY UI93812

     UP23/10/10 P F310

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.