Backwards migration considerations when using z/OS data set encryption

You need to consider the following when backwards migrating a queue manager, which has one or more encrypted data sets.

z/OS® data set encryption is supported on the following IBM® MQ for z/OS data sets:

Active log data sets
Archive log data sets
Page sets
BSDS
SMDS
CSQINP* data sets

There are no backwards migration considerations for BSDS, archive log, or CSINP* data sets.

However, there are considerations for

SMDS
Page set and
Active log

data sets, as using these with z/OS data set encryption is not supported in IBM MQ for z/OS 9.1.0, and earlier, long term support releases.

Prior to backwards migration, all encryption policies for SMDS, page set, and active log data sets need to be removed and the data decrypted. This process is described in Removing data set encryption from a data set.

Attention: If the queue manager to be backwards migrated is part of a queue sharing group (QSG), read the Queue sharing group considerations section first.

Removing data set encryption from a data set

This example describes how to remove data set encryption from the log data set CSQ1.LOGS.LOGCOPY1.DS001. You can use an equivalent process for SMDS and page sets.

The example assumes that:

RACF is the SAF
The queue manager that uses the data set has been stopped
The encryption key label has been associated with the generic RACF profile CSQ1.LOGS.*

Carry out the following procedure:

Copy the data from the data set to a back-up data set.

Define a backup data set which is not associated with an encryption key label.

Note: Replace ++EXTDCLASS++ with the name of the extended format data class you want to use for the data set.


//DEFINE EXEC PGM=IDCAMS,REGION=0M                           
//SYSPRINT DD SYSOUT=*                                             
//SYSIN    DD *                                                    
  /*-------------------------------------------------------------*/
  /* DEFINE UNENCRYPTED DATA SET                                 */
  /*-------------------------------------------------------------*/
  DEFINE CLUSTER                                     -             
         (NAME(CSQ1.BAK.LOGS.LOGCOPY1.DS001)         -             
         LINEAR                                      -             
         SHAREOPTIONS(2 3)                           -             
         MODEL(CSQ1.LOGS.LOGCOPY1.DS001)             -             
         DATACLAS(++EXTDCLASS++))                                       
/*

Copy the data from the original data set to the backup. This step decrypts the data.


//COPY     EXEC PGM=IDCAMS,REGION=0M                               
//SYSPRINT DD SYSOUT=*                                             
//SYSIN    DD *                                                    
  /*-------------------------------------------------------------*/
  /* COPY DATA INTO UNENCRYPTED DATA SET                         */
  /*-------------------------------------------------------------*/
  REPRO INDATASET(CSQ1.LOGS.LOGCOPY1.DS001)           -             
        OUTDATASET(CSQ1.BAK.LOGS.LOGCOPY1.DS001)                    
/*

Delete the original data set


//DELETE   EXEC PGM=IDCAMS,REGION=0M                               
//SYSPRINT DD SYSOUT=*                                             
//SYSIN    DD *                                                    
  /*-------------------------------------------------------------*/
  /* DELETE ORIGINAL                                             */
  /*-------------------------------------------------------------*/
  DELETE ('CSQ1.LOGS.LOGCOPY1.DS001')                               
/*

Rename the backup to the original data set name. The data remains unencrypted

//RENAME   EXEC PGM=IDCAMS,REGION=0M                                
//SYSPRINT DD SYSOUT=*                                              
//SYSIN    DD *                                                     
  /*-------------------------------------------------------------*/ 
  /* RENAME UNENCRYPTED DATA SET                                 */ 
  /*-------------------------------------------------------------*/ 
  ALTER CSQ1.BAK.LOGS.LOGCOPY1.DS001'                 -             
         NEWNAME('CSQ1.LOGS.LOGCOPY1.DS001)                         
  ALTER 'CSQ1.BAK.LOGS.LOGCOPY1.DS001.*'               -             
         NEWNAME('CSQ1.LOGS.LOGCOPY1.DS001.*')                       
/*

Optionally, repeat this process for other data sets that have an encryption key label associated with them through the CSQ1.LOGS.* generic profile.
Optionally, if all data sets associated with the CSQ1.LOGS.* generic profile have been decrypted, remove the DATAKEY associated with the generic profile by issuing the following command
```
ALTDSD 'CSQ1.LOGS.*' DFP(RESOWNER(QMCSQ1) DATAKEY(CSQ1DSKY))
```
Refresh the generic dataset profiles by issuing the following command:
```
SETROPTS GENERIC(DATASET) REFRESH
```
Restart the queue manager.
If the encryption key is no longer needed, delete it, and delete its associated RACF profile from the CSFKEYS class.

Queue sharing group considerations

If a queue manager that is part of a queue sharing group is going to be backwards migrated to a version of IBM MQ for z/OS that does not support data set encryption then all of the active log data sets and SMDS of all queue managers in the QSG need to have their data set encryption policies removed, and their data decrypted.

This applies regardless of whether a single member of QSG is backwards migrated, or all members of the QSG.

You can achieve removal of encryption policies, and decryption of data, without a full QSG outage by:

Shutting down each queue manager in the QSG in turn, removing the encryption policies and decrypting the data from its active logs, using the process described in Removing data set encryption from a data set.
If the queue manager is to be backwards migrated, its page set should also be decrypted at this time. Then restart the queue manager.
Removing the encryption policies and decrypting the data for the SMDS of each individual CF structure in turn by:
1. Issuing the command
```
RESET SMDS(*) ACCESS(DISABLED) CFSTRUCT(structure-name)
```
  to suspend queue manager access to the SMDS. During this time the data on the shared queues associated with the SMDS will be temporarily unavailable.
2. Following the process in Removing data set encryption from a data set for each data set which makes up the SMDS.
3. Issuing the command
```
RESET SMDS(*) ACCESS(ENABLED) CFSTRUCT(structure-name)
```
  to resume queue manager access to the SMDS.

Using z/OS data set encryption with a queue manager that does not support it

If you accidentally backwards migrate a queue manager to a version of IBM MQ for z/OS that does not support data set encryption, and forget to remove the encryption policies and decrypt the data you get an error when the queue manager tries to access the data set.

The error depends on the data set type and is shown in the following table.

Note: If one or more of these errors occur, you need to follow the processes described in Removing data set encryption from a data set for the affected data set. These can be performed without changing the version of IBM MQ for z/OS.

Data set	Error if queue manager does not support z/OS data set encryption
Page set 0	Abend 5C6-00C91400 at queue manager start
Page sets 1-99	MQRC 2193 "Pageset error" when accessing page set, for example, on MQPUT
Active log	Abend 5C6-00E80084 at queue manager start
SMDS	Message IEC161I-122 logged "The data set has a KEYLABEL, but the user did not specify that the application could handle encryption". SMDS marked AVAIL(ERROR).