Configuring LDAPS (LDAP via SSL) for CRN/IBM COGNOS BI

Resolving The Problem

The SSL Certificate Database IBM Cognos BI expects is in fact an Netscape Security Services (NSS) certificate database. This database consists of two proprietary Netscape format files which must be located in the same folder and should be perceived as a single entity. The first file is called cert7.db or cert8.db, the second file is called key3.db. To create the certificate database files a tool from the NSS toolkit is needed called certutil. Recent versions of certutil (NSS 3.6+) no longer create cert7.db files, but only the successor cert8.db.

As of version 10 IBM Cognos BI does support both formats. cert8.db files and cert7.db files. However previous versions of IBM Cognos BI don't support cert8.db files and explicitly require a cert7.db file.
This implies using different versions of the NSS toolkit and it's certutil depending on the version of IBM Cognos BI.

Obtain the NSS toolkit

• For IBM Cognos BI version 8 and prior...
  ...one has to use a legacy version of NSS, the build 3.4.2. However there is an apparent issue with this version when dealing with CA certificates (trust is not established if only CA certificate is provided in the database) so that as of now the only eligible version of NSS which delivers a working cert7.db is NSS 3.3.2. (refer to Related Documents section for download link)
  The package requires some underlying base libraries (NSPR v4.1.2) as well (again download link in Related Documents section)
  In both locations select the sub-folder representing your Operating System (WINNT is suitable for all Windows versions) and choose the "OPT.OBJ" folder. Download the ZIP file.
  
  
• For IBM Cognos 10...
  ...download the most recent version of NSS from ftp.mozilla.org/pub/mozilla.org/security. Unfortunately Mozilla stopped providing binary releases, refer to Related Documents section for a download link to one of the most recent binaries which is known to work well.
  Select the sub-folder representing your Operating System (msvc9 is suitable for all Windows versions) and choose the "OPT.OBJ" folder. Download the ZIP file.
  
  

Install the certutil tool:

• unzip each downloaded file into a separate folder, like the NSPR ZIP to <NSPR_PATH> and the NSS ZIP file to <NSS_PATH>.
  Each folder will contain subdirectories /bin, /inculde and /lib.
  The certutil executable is located in the /bin subdirectory of the <NSS_PATH> folder.
• One must add the NSS and NSPR libs to the environment so certutil can pick them up.
  This is achieved by adding can be achieved by either
  • copying the contents of the NSPR and NSS folders' /lib subfolders into the NSS folder's /bin subfolder
  or
  • adding NSPR and NSS folder's /lib subfolder to the library path for your system
    Example on Windows: open a shell, cd to the folder you unpacked NSS into and cd then into the /bin subfolder, type SET PATH=<NSPR_PATH>/lib;<NSS_PATH>/lib;%PATH% , hit return,
    now call certuil by entering certutil and press return.
  The actual steps may vary depending on where the ZIP files have been unzipped to and platform, the point is to make available the contents of BOTH /lib directories to the system.

Create Keystore

IBM Cognos BI can establish trust to a presented server certificate for LDAPS connection based on either the server certificate importet as a valid signer certificate or the root CA certificate which signed the server certificate.
It's a common and proven practice to use the CA root certificate, so this is preferable. If you should choose to fo forward with the server certificate though, it is sufficient to import the server certificate only, you don't necessarily have to import the CA certificate as well.

Steps:

1. Aquire the certificate(s) to use in Base-64 encoded X.509 (PEM) format.
   To ease reading it is assumed they were saved asserver.cert or CA.cert.
   
   You can try getting the server certificate easily by accessing the LDAP using a browser by HTTPS at the LDAPS port (usually 636). Example: https://myldapserver:636.
   Once the browser prompts to accept or inspect the certificate, select to inspect it and save it to a file from there. This works for Internet Explorer and Mozilla/Netscape. However, it may not work for all LDAP servers as they prevent https connections
   
   Another possibility is to use OpenSSL's s_client modus to simulate a client and retrieve the certificate like:
   openssl s_client -connect host:port -showcerts
   This will print out all the certificates the server presents (server + CA) to the console where you can obtain them by copy & paste.
   
   Or the most straight forward approach, ask the LDAP server administrator for the certificate.


2. Create a subdirectory to hold the certificate database which will be created in the next steps, for example "mykeys".


3. Create a new NSS certificate database by issuing:
   
   certutil -N -d <cert_directory>
   example: certutil -N -d C:\path\to\mykeys
   This will create a cert7.db or cert8.db file and a key3.db file in the directory created in 2.
   Those consitute the certificate database and hence the subdirectory should be treated as a single entity, always keep these files in one single directory.


4. Add the certificate you want to use to the new certificate database:
   • For a server cert issue:
     
     certutil -A -n <cert_name> -d <cert_directory> -i <certificate_file> -t P
     
     Example: certutil -A -n MyServer -d c:\path\to\mykeys -i server.cert -t P
     
     
   • For a CA cert issue:
     
     certutil -A -n <cert_name> -d <cert_directory> -i <certificate_file> -t C,C,C
     
     Example: certutil -A -n MyCA -d c:\path\to\mykeys -i CA.cert -t C,C,C
     
   
   where
   
   

   <cert_name>

   is an arbitrary name you assign to the certificate in the certificate database as an alias. Using the CA name or NetBIOS hostname is a good practice.

   
   

   <cert_directory>

   specifies the subdirectory for the certificate database to use.
   Certutil will have created a cert7.db/cert8.db (& key3.db) in this location in step 3.
   



5. Verify the certificate import
   To verify the import was successful and the trust option is correct, issuecertutil -L -d mykeys An Example output that has both a Server certificate and a Root CA certificate correctly installed will look like this:
   

   Certificate Name	Trust Attributes
   ldap1.myserver.com	P,,
   My Root CA	C,C,C
   p Valid peer
   P Trusted peer (implies p)
   c Valid CA
   T Trusted CA to issue client certs (implies c)
   C Trusted CA to certs(only server certs for ssl) (implies c)
   u User cert
   w Send warning

Complete the setup in Cognos Configuration

Provide the absolute path to the cert7.db/cert8.db file (ie: c:\path\to\mykeys\cert7.db) for the SSL Certificate Database property in Cognos Configuration. Dont forget to adjust the port to the LDAPS port, usually 636.
You can now right-click and test the LDAP namespace at this time. If the SSL connection can be established successfully the test will succeed

Save configuration and restart the Cognos product for the changes to take effect.