Remote queuing of privacy-protected messages on z/OS
This example details the Advanced Message Security policies and certificates needed to send and retrieve privacy-protected messages to and from queues managed by two different queue managers. The two queue managers can be running on the same z/OS® system, or on different z/OS systems, or one queue manager can be on a distributed system running Advanced Message Security.
The example queue managers and queues are:
BNK6 - Sending queue manager BNK7 - Recipient queue manager FIN.XFER.Q7 - Remote queue on BNK6 FIN.RCPT.Q7 - Local queue on BNK7
Note: For this example, BNK6 and BNK7 are queue managers running on different z/OS systems of the same name.
These users are used:
WMQBNK6 - AMS task user on BNK6 WMQBNK7 - AMS task user on BNK7 TELLER5 - Sending user on BNK6 FINADM2 - Recipient user on BNK7
The steps to configure this scenario are as follows:
Create the user certificates
In this example, two user certificates are required. These are the sending user's certificate which is needed to sign messages, and the recipient user's certificate which is needed to encrypt and decrypt the message data. The sending user is 'TELLER5' and the recipient user is 'FINADM2'.
The Certificate Authority (CA) certificate is also required. The CA certificate is the certificate of the authority that issued the user's certificate. This can be a chain of certificates. If so, all certificates in the chain are required in the key ring of the Advanced Message Security task user, in this case user WMQBNK7.
A CA certificate can be created using the RACF® RACDCERT command. This certificate is used to issue user certificates. For example:
RACDCERT CERTAUTH GENCERT SUBJECTSDN(CN('BCOCA') O('BCO') C('US'))
KEYUSAGE(CERTSIGN) WITHLABEL('BCOCA')
This RACDCERT command creates a CA certificate which can then be used to issue user certificates for users 'TELLER5' and 'FINADM2'. For example:
RACDCERT ID(TELLER5) GENCERT SUBJECTSDN(CN('Teller5') O('BCO') C('US'))
WITHLABEL('Teller5') SIGNWITH(CERTAUTH LABEL('BCOCA'))
KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN)
RACDCERT ID(FINADM2) GENCERT SUBJECTSDN(CN('FinAdm2') O('BCO') C('US'))
WITHLABEL('FinAdm2') SIGNWITH(CERTAUTH LABEL('BCOCA'))
KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN)
Your installation will have procedures for choosing or creating a CA certificate, as well as procedures for issuing certificates and distributing them to relevant systems.
When exporting and importing these certificates, Advanced Message Security requires:
- The CA certificate (chain).
- The sending user certificate and its private key.
- The recipient user certificate and its private key.
If you are using RACF, the RACDCERT EXPORT command can be used to export certificates to a data set, and the RACDCERT ADD command can be used to import certificates from the data set. For more information about these and other RACDCERT commands, refer to z/OS: Security Server RACF Command Language Reference.
The certificates in this case, are required on the z/OS system running queue manager BNK6 and BNK7.
In this example, the sending and recipient certificates must be imported on the z/OS system running BNK6, and the CA and recipient certificates must be imported on the z/OS system running BNK7. When the certificates have been imported, the user certificates require the TRUST attribute. The RACDCERT ALTER command can be used to add the TRUST attribute to the certificate. For example:
On BNK6:
RACDCERT ID(TELLER5) ALTER (LABEL('Teller5')) TRUST
RACDCERT ID(FINADM2) ALTER (LABEL('FinAdm2')) TRUST
On BNK7:
RACDCERT ID(FINADM2) ALTER (LABEL('FinAdm2')) TRUST
Connect certificates to relevant key rings
When the required certificates have been created or imported, and set as trusted, they must be connected to the appropriate user key rings on the z/OS systems running BNK6 and BNK7.
To create the key rings use the RACDCERT ADDRING command:
On BNK6:
RACDCERT ID(WMQBNK6) ADDRING(drq.ams.keyring) RACDCERT ID(TELLER5) ADDRING(drq.ams.keyring)
This creates a key ring for the Advanced Message Security task user and a key ring for the sending user on BNK6. Note that the key ring name drq.ams.keyring is mandatory, and the name is case-sensitive.
On BNK7:
RACDCERT ID(WMQBNK7) ADDRING(drq.ams.keyring) RACDCERT ID(FINADM2) ADDRING(drq.ams.keyring)
This creates a key ring for the Advanced Message Security task user and a key ring for the recipient user on BNK7.
When the key rings have been created, the relevant certificates can be connected.
On BNK6:
RACDCERT ID(WMQBNK6) CONNECT(ID(FINADM2) LABEL('FinAdm2')
RING(drq.ams.keyring) USAGE(SITE))
RACDCERT ID(TELLER5) CONNECT(ID(TELLER5) LABEL('Teller5')
RING(drq.ams.keyring) DEFAULT USAGE(PERSONAL))
On BNK7:
RACDCERT ID(WMQBNK7) CONNECT(CERTAUTH LABEL('BCOCA')
RING(drq.ams.keyring))
RACDCERT ID(FINADM2) CONNECT(ID(FINADM2) LABEL('FinAdm2')
RING(drq.ams.keyring) DEFAULT USAGE(PERSONAL))
The sending and recipient user certificates must be connected as DEFAULT. If either user has more than one certificate in its drq.ams.keyring, the default certificate is used for signing and encryption/decryption purposes.
On BNK6, the recipient user's certificate must also be connected to the Advanced Message Security task user's key ring with USAGE(SITE). This is because the Advanced Message Security task needs the recipient's public key when encrypting the message data. The USAGE(SITE) prevents the private key from being accessible in the key ring.
The creation and modification of certificates is not recognized by Advanced Message Security until the queue manager is stopped and restarted, or the z/OS MODIFY command is used to refresh the Advanced Message Security certificate configuration. For example:
On BNK6:
F BNK6AMSM,REFRESH,KEYRING
On BNK7:
F BNK7AMSM,REFRESH,KEYRING
Create the Advanced Message Security policies
In this example, privacy-protected messages are put to remote queue FIN.XFER.Q7 on BNK6 by an application running as user 'TELLER5', and retrieved from local queue FIN.RCPT.Q7 on BNK7 by an application running as user 'FINADM2', so two Advanced Message Security policies are required.
Advanced Message Security policies are created using the CSQ0UTIL utility that is documented at The message security policy utility (CSQ0UTIL).
Use the CSQ0UTIL utility to run the following command to define a privacy policy for the remote queue on BNK6:
setmqspl -m BNK6 -p FIN.XFER.Q7 -s SHA1 -e 3DES -a CN=Teller5,O=BCO,C=US -r CN=FinAdm2,O=BCO,C=US
In this policy, the queue manager is identified as BNK6. The policy name and associated queue is FIN.XFER.Q7. The algorithm that is used to generate the sender's signature is SHA1, the distinguished name (DN) of the sending user is 'CN=Teller5,O=BCO,C=US', and the recipient user is 'CN=FinAdm2,O=BCO,C=US'. The algorithm that is used to encrypt the message data is 3DES.
Also, use the CSQ0UTIL utility to run the following command to define a privacy policy for the local queue on BNK7:
setmqspl -m BNK7 -p FIN.RCPT.Q7 -s SHA1 -e 3DES -a CN=Teller5,O=BCO,C=US -r CN=FinAdm2,O=BCO,C=US
In this policy, the queue manager is identified as BNK7. The policy name and associated queue is FIN.RCPT.Q7. The algorithm expected for the sender's signature is SHA1, the distinguished name (DN) of the sending user is expected to be 'CN=Teller5,O=BCO,C=US', and the recipient user is 'CN=FinAdm2,O=BCO,C=US'. The algorithm that is used to decrypt the message data is 3DES.
After defining the two policies, either restart the BNK6 and BNK7 queue managers, or use the z/OS MODIFY command to refresh the Advanced Message Security policy configuration. For example:
On BNK6:
F BNK6AMSM,REFRESH,POLICY
On BNK7:
F BNK7AMSM,REFRESH,POLICY