IBM Support

How to configure (force) Controller to use TLS 1.2

How To


Summary

Customer would like to force Controller to use TLS 1.2 (in other words, disable TLS 1.1 and 1.0).

How do they do this?

Objective

Force Controller to use TLS 1.2.
More Information:
By default, IBM Java has TLS 1.0 enabled. To enable and force TLS 1.2 you need to append two java runtime arguments:
-Dcom.ibm.jsse2.overrideDefaultTLS=true
-Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12
 
However, this must be done in several places (because the Controller architecture is made up of a number of separate components).

Environment

The instructions are based on Controller 10.3.1 / 10.4.x
  • They may also work on older/newer versions.

Steps

Perform the following steps for each of the Controller-related components:
(1) Controller Web (backend)
1. Browse to the folder:    ...\ccr_64\fcmweb\wlp\etc\
  • TIP:  By default this is located here:    C:\Program Files\ibm\cognos\ccr_64\fcmweb\wlp\etc\
2. Open the following file in NOTEPAD:   jvm.options
3. Add the following lines (at the end):
-Dcom.ibm.jsse2.overrideDefaultTLS=true
-Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12
4. Save changes
5. Obtain downtime (no users using Controller Web) and restart the Windows service:    IBM Cognos Controller Web
~~~~~~~~~~~~~~~~~~~~~~~~
TIP: The above step also ensures that the "IBM Cognos Controller Reports" service (also known as 'ccrReports' engine/functionality) uses TLS 1.2.
~~~~~~~~~~~~~~~~~~~~~~~~
(2) Java Proxy service
1. Browse to the folder:    ...ccr_64\server\
  • TIP:  By default this is located here:    C:\Program Files\ibm\cognos\ccr_64\server\
2. Open the following file in NOTEPAD:   CCRProxy.options
3. Add the following lines (at the end):
-Dcom.ibm.jsse2.overrideDefaultTLS=true
-Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12
4. Save changes
5. Obtain downtime (no users using any JAVA-related functionality) and restart the Windows service:    IBM Cognos Controller Java Proxy
 
(3) DBConv utility
At the time of writing, current versions of Controller do not have an 'options' file for DBConv, so a different method needs to be performed.
  • In future versions of Controller, there will be a simpler method to achieve the following:
1. Browse to the folder:    ...ccr_64\
  • TIP:  By default this is located here:    C:\Program Files\ibm\cognos\ccr_64\
2. Create a file called:   DbConv.bat
3. Edit the file in NOTEPAD, and add the following contents:
  
"C:\Program Files\IBM\cognos\ccr_64\bin\jre\8.0\bin\java.exe" -cp com.ibm.cognos.ccr.dbconv.ui.DbConvGUI"C:\Program Files\ibm\cognos\ccr_64\bin64\jre\8.0\bin\javaw.exe" -Dcom.ibm.jsse2.overrideDefaultTLS=true -Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12 -cp "C:\ProgramFiles\ibm\cognos\ccr_64\DbConv.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\antlr-3.2.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ccr-common.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ccr-integration-server.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ccr-integration.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ccr-xml.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\cglib-nodep-2.1_3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-beanutils-1.8.3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-beanutils-bean-collections-1.8.3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-beanutils-core-1.8.3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-cli-1.1.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-codec-1.8.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-collections-3.2.1.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-dbcp-1.2.2.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-io-2.4.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-lang-2.3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-logging-1.1.1.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\commons-pool-1.3.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\db2jcc.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\DBConv.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\icu4j-4_8_1_1.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\jsr173_1.0_api.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\jython.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\log4j-1.2.8.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ngtm1api.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\ojdbc6.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\resolver.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\spring.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\sqljdbc4.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\stringtemplate-3.2.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\xbean.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\xbean_xpath.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\xmlbeans-qname.jar";"C:\Program Files\ibm\cognos\ccr_64\server\integration\xmlpublic.jar" com.ibm.cognos.ccr.dbconv.ui.DbConvGUI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
IMPORTANT: You will need to edit/change the contents (above) slightly if:
  • You have installed Controller to a non-default location
  • You are using Microsoft SQL with a JAR file whose name is different from:    sqljdbc4.jar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4. Save the file
5. Run the file:  DbConv.bat
6. Whilst inside the Database Conversion utility, you can now connect to your databases (and create tables / upgrade table schemas as required).
     
(4) FAP
1. Browse to the folder:    ...\ccr_64\server\FAP\
2. Create 'jvm.options' by right-clicking and choosing 'New - Text Document'
3. Open the following file in NOTEPAD:   jvm.options
4. Add the following lines (at the end):
-Dcom.ibm.jsse2.overrideDefaultTLS=true
-Dcom.ibm.jsse2.overrideDefaultProtocol=TLSv12
5. Save changes
6. Obtain downtime (no users using Controller FAP) and restart the Windows service:    IBM Cognos FAP Service
(5) Enable TLS for .NetFramework (on both client and server)
On the Controller application server:
You must perform the following steps (otherwise the program 'Controller Configuration' will give an error 'The underlying connection was closed' when trying to verify the connection inside 'Report Server' section):
1. Open the registry editor, by clicking on ‘Start’ menu and typing:    REGEDIT
2. Navigate to the following path: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
3. Right-click on v4.0.30319 and select New –> DWORD (32-bit)
  • Set the name to: SchUseStrongCrypto
  • Set the value to 00000001
On every client device
You must perform the following:
1. Open the registry editor, by clicking on ‘Start’ menu and typing:    REGEDIT
2. Navigate to the following path: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
3. Right-click on v4.0.30319 and select New –> DWORD (32-bit)
  • Set the name to: SchUseStrongCrypto
  • Set the value to 00000001
~~~~~~~~~~~~~~~~~~~~~
If your client device has a 64-bit version of Excel installed, then you can skip the next steps.
  • However, if you have a 32-bit version of Excel then you must perform the next steps (see separate IBM Technote #0956557 for why).
~~~~~~~~~~~~~~~~~~~~~
4. Navigate to the following path: [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
5. Right-click on v4.0.30319 and select New –> DWORD (32-bit)
  • Set the name to: SchUseStrongCrypto
  • Set the value to 00000001
    
(6) Cognos Analytics
Modern versions of Controller use a Cognos Analytics (CA) server for some of its functionality. Therefore you will need to modify the CA 'content manager' server so that it can successfully connect to the database server (for example SQL server), using TLS 1.2.
  • See separate IBM Technote #2016796 for full details.

Additional Information

If you intend to secure your Controller system using HTTPS (rather than the default HTTP) then there are other steps that you will need to perform (for example importing SSL certificates into the Controller client JAVA keystore).
  • TIP: For more information about securing the Controller system with HTTPS see separate IBM Technote #2004921.

Document Location

Worldwide

[{"Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"ARM Category":[{"code":"a8m0z0000000AxnAAE","label":"Documentation"}],"ARM Case Number":"","Platform":[{"code":"PF033","label":"Windows"}],"Version":"All Version(s)"}]

Document Information

Modified date:
16 September 2020

UID

ibm10883036

Page Feedback