SSL requires the use of certificates. A StarPipes server certificate must be installed in the Windows certificate store prior to configuring an SSL listener, and a client certificate may be optionally required for all clients connecting to the StarPipes server via SSL. In the case where multiple certificate authorities are involved, you may need to ensure that the StarPipes server, the hosts that it is connecting to, and clients that are connecting to StarPipes recognize the certificate authorities involved so that certificates are trusted.
Below are some typical scenarios:
Requesting and installing a server certificate before enabling the SSL listener
Requesting and installing a client certificate
Use regedit to create a new string value named Subject in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\StarQuest\StarPipesNT\StarPipesConfig. Set the value to the desired name; this is typically the fully qualified hostname of the server running StarPipes e.g. myserver.mydomain.com. You will use this name when creating the certificate request. If you do not configure this value, StarPipes will look for a valid certificate that contains the Subject StarPipes.
Most public Certificate Authorities publish instructions for creating a CSR from Windows; for example, you can use these instructions from Entrust and RapidSSL as an illustrated guide.
Start MMC
Select Add/Remove Snap-in... from the File menu
Choose Certificates from Available Snap-ins and select the Add Button.
Select the radio button to manage certificates for Computer Account.
Choose the radio button to manage the Local Computer.
Click Finish and OK.
Expand Certificates (Local Computer)/Personal.
Right-click on the Personal folder and select
All Tasks/Advanced Operations/Create Custom Request
The CSR Generation Wizard will open. Click Next.
Select the option to Proceed without enrollment policy. Click Next.
Click Next at the No Template/ PKCS #10 window.
Expand the Details drop down menu and click Properties.
Enter a Friendly Name of your choosing.
Go to the Subject tab. In the Subject name box, enter appropriate values. The most important item (and usually the only required one) is Common Name (CN); this must match the value you entered in the registry above.
Example:
CN = myserver.mydomain.com
O = Your organization name
OU = Department or Division (optional)
S = State
L = City or Locality
C = Country
Click the Private Key tab.
Under Key Options, set Key size: 2048 and select the checkbox to Make private key exportable.
Under Key Permissions, select the checkbox for custom permissions and examine the key permissions. If the StarPipes service will be running as Local System Account, make sure that the System group has access to the private keys; if the StarPipes service will be running as a different user, make sure that user has access.
Click Next > Click Browse and select a location to save the CSR file as Base 64 (text) format. Enter a name for the file and click Save.
Click Finish.
The following example shows the use of Microsoft Active Directory Certificate Services. Both Certificate Services and the WWW Publishing Service (IIS) should be running on the certificate server. Note that Certificate Services do not necessarily need to be run on a domain controller.
Using a public Certificate Authority is similar in concept but differs in the details. Using a public Certificate Authority usually involves some form of verification process.
Use Internet Explorer to open https://mycertsrv/certsrv. You will be prompted for the credentials of a domain user.
On the Welcome page, select Request a certificate
On the Request a Certificate page, select submit an advanced certificate request.
On the Advanced Certificate Request page, select Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file.
On the Submit a Certificate Request or Renewal Request page
Paste in the contents of the CSR file created above into the Saved Request field; this is a plain text file and can be opened in Notepad.
Select Web Server from the Certificate Template dropdown and click Submit.
If the Certificate Server has been configured to automatically issue certificates (this is typically defined in the Certificate Template), the certificate is already available; select Download certificate chain as Base 64 encoded. If issuing the certificate requires approval from the administrator, the request will be set to pending, and you can retrieve the certificate later through the same web interface.
If necessary, the Certificate Server administrator approves the request using the following steps on the Certificate Server:
Start MMC.
Select Add/Remove Snap-in... from the File menu.
Select the Add Button and choose Certification Authority.
Choose Local Computer.
Expand the Certification Authority tree and open the Pending Requests folder.
Right click on the Request and select Issue from All Tasks.
Back on the StarPipes machine, retrieve the certificate:
Use Internet Explorer to open https://mycertsrv/certsrv and log on as a domain user if necessary.
Select View the Status of a Pending Certificate Request.
Select the certificate request and select Download certificate chain as Base 64 encoded.
As above, Start MMC, Select Add/Remove Snap-in... from the File menu, choose Certificates and select the Add Button, Select the radio button to manage certificates for Computer Account, Choose the radio button to manage the Local Computer. and Expand Certificates (Local Computer)/Personal.
Right-click on the Personal folder and select All Tasks/Import...
Browse to the location of the Base 64 certificate file you received from the CA. If you do not see the file listed (e.g. you saved the file with an extension of .txt or something other than the extensions listed in the dropdown of the browse window), select All files (*.*) from the dropdown. Select the certificate file and click OK.
The server certificate (and possibly the Certificate Authority certificate) will appear in the Personal/Certificate folder. Double-click the server certificate to view its details. Check that the statement You have a private key that corresponds to this certificate appears.
After installing the server certificate, you can now create the SSL listener in StarPipes.
Open the StarPipes Management Console.
Right-click on the server name and select Properties.
On the Listeners tab, select Add, configure a port, select the SSL/TLS checkbox, and click OK.
If all is well, the listener is created and will show a status of Running. Test that you can connect with an SSL-enabled DRDA client such as StarSQL or StarSQL for Java.
If you get the error A server certificate could not be found, the listener status will show as Error. Once a valid certificate is installed, restart the StarPipes service and check that the error TLA0055 Unable to find server certificate for SSL listener no longer appears in the Application event log.
Requesting and installing a client (aka user) certificate is necessary if your StarPipes server is connecting to another StarPipes server that requires a client certificate, or if you are configuring a client to communicate with a StarPipes server configured to require a client certificate. Requesting a client certificate from Microsoft Active Directory Certificate Services is similar to the process above except
The Subject (CN) is configured in a registry value named ClientSubject; default value is StarPipesClient. In the case of a user certificate issued by a Microsoft Certificate Server, this value is the name of the domain user that was used when submitting the CSR via Internet Explorer.
Select User or Client Authentication Certificate for Certificate Template or Type of Certificate Needed.
Unless you are using a client certificate from a public certificate authority, make sure that you import the CA certificate of the CA that issued the client certificate into the Trusted Root Certification Authorities folder of the StarPipes server that is configured to require a client certificate - i.e. the CA certificate should exist on both StarPipes systems.
The above examples demonstrate the use of Microsoft Active Directory Certificate Services. Depending on your host and client environments, you may need to work with certificates created or used by other certificate mechanisms such as:
The Java keytool application, included in the JRE.
IBM i Digital Certificate Manager (DCM)
IBM Global Security Kit (GSKit), included with IBM DB2 LUW.
Commercial third party certificate authorities
If you are using a mix of Certificate Authorities, you may need to export and import certificates between certificate stores.
Below is an example of connecting an IBM System i server running i 7.x as a client to a StarPipes server. If the i 7.1 machine does not trust the CA that issued the Starpipes server certificate, you will get an error "CPD3E3C DDM TCP/IP Secure Sockets error occurred on SSL_Init() - Reason code 23" (reason code 23 is defined as SSL_ERROR_NOT_TRUSTED_ROOT in qsossl.h) when attempting a connection from the i Server to StarPipes.
On the Windows machine running StarPipes, use MMC to export the root certificate of your CA to a .ARM file.
On the i 7.x machine, Use DCM to create a certificate store and import the ARM file.
On the i 7.1 machine, use the following command to access a database called "MYRDB" through a StarPipes server at IP address "myspip" listening on port 448:
ADDRDBDIRE RDB(MYRDB) RMTLOCNAME(myspip *IP) PORT(448) SECCNN(*SSL)