Configuring CICS® Distributed Program Link (DPL) Agent to use HTTPS
HCL OneTest™ API and HCL OneTest™ API Agents do not trust self-signed certificates by default, such as the SSL certificate generated for use in the HCL Quality Server server configuration. To use HTTPS, configure a CICS® Distributed Program Link (DPL) Agent that communicates with HCL Quality Server.
About this task
- Exporting the HCL Quality Server server certificate to a file
- Importing the HCL Quality Server server certificate into the RACF database
For more information about the RACF commands used in this
topic, see RACF command syntax.
Note: Mozilla Firefox
was used to capture the screen shots used in this topic. The options
you see on the user interface might be different in Microsoft Internet
Explorer and Google Chrome.
Exporting the HCL Quality Server server certificate to a file
Procedure
-
Verify that HCL Quality Server server is
running. To do so, see if the RTCP icon in the lower bottom corner of the
HCL OneTest™ API
window has turned green.
When HCL Quality Server starts up, you will see an orange icon. Wait for it to change to green. If the icon remains red, which means that HCL OneTest™ API cannot communicate with HCL Quality Server, try the following troubleshooting tips:
- Go to HCL Quality Server ( ) and verify that Automatically start HCL Quality Server and Proxy is selected. You must restart HCL OneTest™ API for any change in the preference to take effect.
- Go to HCL Quality Server
(
https://localhost:5443/RTCP/
, in case the auto-start preference is enabled) is correct. To confirm that HCL Quality Server is running and is listening on the configured port, open a browser and go to this URL.
and verify that the URL being used to connect to - Review the HCL Quality Server logs.
-
Open HCL Quality Server in a
browser by using its secure URL. For example,
https://myServer:5443/RTCP
. - Click the lock symbol shown in the address bar.
- Click More information in the dialog.
- In the Page Info window, open the Security tab and click View Certificate.
- In the Certificate Viewer window, open the Details tab and export the "HCL OneTest™ API Root CA certificate".
- In the Save Certificate To File dialog,
select PEM against Save as type.
For example,
X.509 Certificate (PEM) (*.crt,*.pem)
. - Click Save. If you open the saved certificate in a text editor, it looks similar to the following snippet:
Results
Importing the HCL Quality Server server certificate into the RACF database
Before you begin
As the currently logged in user, ensure that you have access to the following profiles:
RACDCERT ADDRING
: You must have theSPECIAL
attribute or sufficient authority to modify theIRR.DIGTCERT.ADDRING
resource in theFACILITY
class. The following table shows the authority required for theRACDCERT ADDRING
function:Table 1. Authority required for RACDCERT ADDRING function Access level Purpose READ Create a key ring for your own user ID. UPDATE Create a key ring for another user. READ RACDCERT ADD
:You must have the following authorizations:
- The SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.ADD resource in the FACILITY class for the intended purpose, as shown in Table 1.
READ
access to the data set that contains the certificate being added.
When you, as the current user, have access to ICSF services and the CSFSERV class is active, additional access to resources in the CSFSERV class might be required as follows:- When specifying PKDS, ICSF, or PCICC, you must have READ access to the CSFIQF, CSFPKI, CSFPKRC, and CSFPKRW resources.
- If the certificate you are adding has an ECC key, you must also
have the following access authorities:
- When you specify PKDS, you must have READ access to the CSFDSV and CSFOWH resources.
- When you omit PKDS, you must have READ access to the CSF1PKV, CSF1TRC, CSF1TRD, and CSFOWH resources.
The following table shows the authority required for the RACDCERT ADD function:Table 2. Authority required for the RACDCERT ADD function Access level Purpose READ Add a certificate to your own user ID. UPDATE Add a certificate for another user ID. CONTROL Add a SITE or CERTAUTH certificate. RACDCERT CONNECT
:You must have the SPECIAL attribute or sufficient authority to the following resources in the FACILITY class, based on the certificate owner, key ring owner, and the USAGE value:IRR.DIGTCERT.CONNECT
IRR.DIGTCERT.ADD
USAGE
keyword, you allow a certificate to be connected to a ring and used in a manner that differs from the certificate's original use. For example, by changing the USAGE value, a certificate defined as a user certificate might be used as a certificate-authority certificate. The USAGE keyword is powerful, and must be used in a controlled manner.The following table shows the access control checks that are performed when connecting to your own key ring:Table 3. Access control checks done when connecting to your own key ring USAGE value Your own certificate Anonther user's certificate SITE or CERTAUTH certificate PERSONAL
READ authority to IRR.DIGTCERT.CONNECT UPDATE authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.CONNECT SITE CERTAUTH
CONTROL authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.ADD and UPDATE authority to IRR.DIGTCERT.CONNECT UPDATE authority to IRR.DIGTCERT.CONNECT The following table shows the access control checks that are performed when connecting to another user's key ring:Table 4. Access control checks done when connecting to another user's key ring USAGE value Your own certificate Another user's certificate SITE or CERTAUTH certificate PERSONAL
CONTROL authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.CONNECT SITE CERTAUTH
CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.CONNECT CONTROL authority to IRR.DIGTCERT.CONNECT
Procedure
- Allocate a dataset with the parameters highlighted in the following screen shot:
- Upload the HCL OneTest™ API Root CA certificate to the RACF database by using FTP.
- Define a key ring by using the following command:
The @USERID@ is the z/OS TSO user ID that is running the HCL OneTest™ API CICS DPL Agent, since the DPL Agent runs on the z/OS system on which the CICS region is running. This user ID could be the same as the Windows user ID for HCL OneTest™ API, but that need not necessarily be the case always.RACDCERT ADDRING(RTCPRING) ID(@USERID@)
If the DIGTRING class is RACLISTed, refresh the class to activate your changes by using the following command:SETROPTS RACLIST(DIGTRING) REFRESH
- Add the certificate by using the following command:
RACDCERT ADD('your.upload.dataset.name') CERTAUTH TRUST WITHLABEL('RTCPCA')
If the DIGTCERT or DIGTRING class is RACLISTed, refresh the classes to activate your changes by using the following command:SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
- Connect the certificate to the key ring by using the following
command:
RACDCERT CONNECT(CERTAUTH label('RTCPCA') USAGE(CERTAUTH) RING(RTCPRING))
If the DIGTCERT or DIGTRING class is RACLISTed, refresh the classes to activate your changes by using the following command:SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
- Verify the status of the key ring by using the following
command:
The status of the key ring should be similar to the one shown in the following screen shot:RACDCERT LISTRING(RTCPRING)
- Set the key ring name in the RITAGENT, changing the value
@KEYRING@
to the name of your key ring: