IBM Support

How to add a 3rd Party CA to allow for SSL between components in IBM Cognos Analytics 11

Troubleshooting


Problem

 This document describes how to reset the cryptographic keys, create the certificate request to be signed by your third-party certificate authority and then import the signed certificates.   
Special attention needs to be paid during the process, as when not to launch the Cognos Configuration tool, which could potentially cause corruption and force the process to be restarted.

Cause

The Cognos certificate authority needs to be replaced, or new certificates need to be imported.

Environment

These steps are platform independent.

Resolving The Problem

First, ensure entire IBM Cognos system is shut down. Use appropriate operating system tools to make sure there are no orphan processes.

Ensure that the JAVA_HOME environment variable is set properly to the JRE being used.

To recrypt IBM Cognos Analytics 11 (password default: NoPassWordSet)

Make a backup copy of your ..\configuration directory;

Steps to delete the old cryptographic keys are as follows:

Stop the running of your service in Cognos Configuration.

On the Content Manager computer, click ‘File > Export As’.

Choose ‘Yes’ at the prompt and save the file. For example, name it ‘backup.xml’, which by default is stored in the c11\configuration folder.

Close Cognos Configuration.

On the Content Manager computer
Create a backup of the following files because during the cryptographic keys regeneration process they are re-created and then move or rename them:

The files are:

c11/configuration/cogstartup.xml

c11/configuration/caSerial

c11/configuration/certs/CAMCrypto.status

c11/configuration/certs/CAMKeystore

c11/configuration/certs/CAMKeystore.lock

c11/temp/cam/freshness

Create a backup of the following directories and then move or rename them from the <c11>/configuration directory.  

c11/configuration/csk

In the c11\configuration folder, rename ‘backup.xml’ to ‘cogstartup.xml’.

 WARNING:  Do not start the Cognos Configuration Tool until explicitly instructed, which occurs later in the document.

Open a command prompt as Administrator.
In the command window...
Change directory to ca11_location\bin;


Windows Operating System Request (Change CN, OU, O, L, and C parameters:

CN is set to your Domain

Syntax:

ThirdPartyCertificateTool.(bat|sh) -c -e [-p <keystorePassword>] -a <keyPairAlgorithm> -r <path/to/CertOrCSR> -d <dn> [-H <subjectAlternativeNameDnsNames>] [-I <subjectAlternativeIpAddresses>] [-M <subjectAlternativeEmailAddresses>]

Example:
ThirdPartyCertificateTool.bat -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com"

Example that uses multiple values for the Subject Alternative Name:

Note: use spaces between values not a comma

ThirdPartyCertificateTool.bat -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com server2.domain"

image-20190814135740-1

OR

On unix and Linux Operating System Request (Change CN, OU, O, L, and C parameters:

CN is set to your Domain

./ThirdPartyCertificateTool.sh -c -e -p NoPassWordSet -a RSA -r "request.csr" -d "CN=server.domain.com,OU=Support,O=IBM,L=Ottawa,C=CA" -H "server.domain.com"
 

INFORMATION: Make a new backup of the complete c11\configuration directory.
                       - Include the exported cogstartup.xml in this new backup

                        - Name the backup configuration.waiting_on_certs

The Cognos keystore now contains the private key that is used with the certificates for encryption.  If you encounter an issue where the private key is overwritten before you get the signed certificate imported successfully all of the steps would need to be redone if a backup is not available.

When the certificates arrive, you may:

  - Stop the product
  - Rename the current c11/configuration directory to c11/configuration.original
  - Rename the c11/configuration.waiting to be c11/configuration
  - Continue on with the technote.


Get encrypt.csr signed by your certificate authority (For example, Digicert or Verisign). They return with a Root, Intermediate(optional), and server certificates.

image-20190814135740-2
 

Download the ROOT, Intermediate, and server certificates on the server.

Convert all the certificates to Base-64 encoded X.509 (.CER) format
 

image-20190814135740-3

image-20190814135740-4

For simplicity, rename the certificates as shown in the screen capture:

image-20190814135740-5

As we have intermediate certificate, follow this step:

Use a tool such as Notepad++ and edit the newly created root certificate and copy the code and paste it under newly created intermediate certificate.

image-20190814135740-6

Save as chain.cer

image-20190814135740-7

Copy all these certificates to ca11_location\bin location.

image-20190814135740-8

Run the new CMD as administrator:

Import the certificate in the following order with these commands:

Windows Operating System:

ThirdPartyCertificateTool.bat -i -T -r root.cer -p NoPassWordSet

image-20190814135740-9

ThirdPartyCertificateTool.bat -i -T -r intermediate.cer -p NoPassWordSet

image-20190814135740-10

ThirdPartyCertificateTool.bat -i -e -r server.cer -t chain.cer -p NoPassWordSet

image-20190814135740-11

OR

On unix or Linux Operating systems:


ThirdPartyCertificateTool.sh -i -T -r root.cer -p NoPassWordSet

ThirdPartyCertificateTool.sh -i -T -r intermediate.cer -p NoPassWordSet

ThirdPartyCertificateTool.sh -i -e -r server.cer -t chain.cer -p NoPassWordSet

If we do not have intermediate certificates, we do not need to create the chain certificate.

Run:

Windows Operating System:

ThirdPartyCertificateTool.bat -i -T -r root.cer -p NoPassWordSet

ThirdPartyCertificateTool.bat -i -e -r server.cer -t root.cer -p NoPassWordSet

On Unix or Linux Operating systems:

ThirdPartyCertificateTool.sh -i -T -r root.cer -p NoPassWordSet

ThirdPartyCertificateTool.sh -i -e -r server.cer -t root.cer -p NoPassWordSet


Launch the Cognos Configuration Tool.

Navigate to Cryptography:

Change 'Use third-party CA?' setting to "True";

Change following URIs from HTTP to HTTPS

  • Dispatcher URIs for gateway
    Change External dispatcher URI
    Change Internal dispatcher URI
    Change Dispatcher URI for external applications
    Change Content Manager URIs

image-20190814135740-14

Save configuration;

image-20190814135740-15


Start IBM Cognos Service.
Ensure that the third-party certificates are added to the appropriate Operating System tools like MMC to be trusted by the server.

[{"Product":{"code":"SSTSF6","label":"IBM Cognos Analytics"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Administration and Configuration v11x","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"11.0","Edition":"Edition Independent","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
20 December 2021

UID

swg21992784