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

The configuration process involves two steps:

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 (Projects > Preferences > Server Settings) 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 Project Settings > Server Settings and verify that the URL being used to connect 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.
- 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

The HCL® Quality Server server certificate is exported to a file.

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 the SPECIAL attribute or sufficient authority to modify the IRR.DIGTCERT.ADDRING resource in the FACILITY class. The following table shows the authority required for the RACDCERT 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.

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.

For details about the CSFSERV resources, see z/OS Cryptographic Services ICSF Administrator's Guide.

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

With the 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:
```
RACDCERT ADDRING(RTCPRING) ID(@USERID@)
```
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.
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:
```
RACDCERT LISTRING(RTCPRING)
```
The status of the key ring should be similar to the one shown in the following screen shot:
Set the key ring name in the RITAGENT, changing the value @KEYRING@ to the name of your key ring:

Results

You have configured the CICS® Distributed Program Link (DPL) Agent to use HTTPS. You can now define resources and start the CICS Transaction Server Agent.