Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Using third-party Certification Authority certificates

 

A certificate authority, or certification authority, (CA) is an entity that issues digital certificates. The digital certificate certifies the ownership of a public key by the named subject of the certificate. With this certification, relying parties can trust signatures or assertions made by the private key that corresponds to the public key that is certified.  Decision Support can use self-signed certificates (those not signed by a certificate authority) or those signed by an internal (corporate) or external (public) certificate authority.

Before you begin

  1. Obtain the openssl utility and extract it into a local directory, for example c:\temp\openssl or /tmp/openssl. You can obtain the relevant copy of this utility (for the appropriate operating system) from BMC Communities.  
  2. Set the OPENSSL_CONF environment variable from the command prompt by executing the following command:

    • (Windows)

      SET OPENSSL_CONF=C:\temp\OpenSSL\openssl.cnf

    • (UNIX)

      export OPENSSL_CONF=/tmp/openssl/openssl.cnf 

    • Ensure the openssl binary is executable (UNIX)

      chmod 755 /tmp/openssl/openssl

Generating new certificates

Perform the following high-level steps to generate new certificates:

  1. Generate the Certificate using OpenSSL 
    1. To use a CA-signed certificate, generate a Certificate Signing Request (CSR) and send the CSR to CA. The CA returns its certificate chain, along with the CA certificate. For instructions, see To create a CSR request using OpenSSL.
    2. To use a self-signed certificate see To create a self-signed certificate using OpenSSL.
  2. Configure Apache Web Server with the certificate as noted in To configure Apache Web Server to support CA certificates.
  3. Configure Apache Tomcat with the certificate as noted in To import CA certificates for Apache Tomcat.
  4. Configure IBM Cognos with the certificate as noted in To configure Cognos to support CA certificates.

To create a CSR request using OpenSSL

  1. Log on to a computer where OpenSSL was extracted in the steps above

  2. From the command prompt, navigate to the following directory:

    • (Windows) C:\Temp\OpenSSL
    • (UNIX) /tmp/openssl

    Use the following command to create an RSA private key and generate the CSR in a single step. This command creates the private key and CSR in the directory from where you run the command.

    • (Windows)

      openssl req -out bmcsareports.csr -new -newkey rsa:2048 -nodes -keyout bmcsareports.key

    • (UNIX)

      ./openssl req -out bmcsareports.csr -new -newkey rsa:2048 -nodes -keyout bmcsareports.key
  3. You are prompted to enter the following information for the CSR:
    • Country name
    • Site or Province name
    • Locality name
    • Organization name
    • Organizational Unit name
    • Common name
    • Email address
    • A challenge password
    • (Optional) Company name
  4. The bmcsareports.csr is the output file containing CSR. Send the CSR file to a CA for signing using one of the following methods. 
    1. Have the CSR signed by a commercial CA like Verisign or Thawte or your internal Corporate CA.
    2. CA returns two signed certificate files, one is the CA certificate chain and the other is the application certificate. For example, ca-chain.cert.pem and bmcsareports.pem.

Back to top

To create a self-signed certificate using OpenSSL

  1. Log on to a computer where OpenSSL was extracted in the steps above
  2. From the command prompt, navigate to the following directory:
    • (Windows) C:\Temp\OpenSSL
    • (UNIX) /tmp/openssl

    • Use the following command to create an RSA private key and generate the self-signed certificate in a single step. This command creates the private key and certificate in the directory from where you run the command.

      (Windows):

      openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout bmcsareports.key -out bmcsareports.pem

      (UNIX):

      ./openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout bmcsareports.key -out bmcsareports.pem

Back to top

To configure Apache Web Server to support CA certificates

  1. Copy the certificate private key file (bmcsareports.key), and two CA certificate files (ca-chain.cert.pem and bmcsareports.pem) in the BDS_HOME\webserver\conf folder. All the certificates must be PEM (Base-64 encoded ASCII) formatted. You can use OpenSSL to convert certificates into the PEM format.

    Tip

    To verify that a file is PEM-formatted either:

    • Open the file and ensure that the contents of the file are enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" tags.
      OR
    • Run the following command:
      openssl x509 -in bmcsareports.pem -text -noout
  2. Navigate to the BDS_HOME\webserver\conf\extra folder, open the httpd-ssl.conf file, and do the following:
    1. Search for SSLCertificateKeyFile and specify the full path of the certificate private key file. For example: SSLCertificateKeyFile "C:/Program Files (x86)/BMC/BDSSA/webserver/conf/bmcsareports.key".
      Replace this file with the bmcsareports.key generated above.
    2. If the CA certificate chain is available, search for SSLCACertificateFile and uncomment the line containing this entry, and specify the full path of the CA certificate file. For example: SSLCACertificateFile "C:/Program Files (x86)/BMC/BDSSA/webserver/conf/ca-chain.cert.pem".
      Add/Replace this file with the one obtained from the CA that signed the server's certificate.

    3. Search for  SSLCertificateFile and uncomment the line containing this entry, and specify the full path of the signed (CA- or self-) certificate file. For example: {{code language="none"}}


      {{/code}}

      SSLCertificateFile "C:/Program Files (x86)/BMC/BDSSA/webserver/conf/bmcsareports.pem".
      Replace this file with the bmcsareports.pem generated above or obtained from the CA.

  3. Restart the Apache Web Service
    1. Windows - Restart the Apache Web Server service from the Windows services menu
    2. Unix - use the <bdssa install>/webserver/bin/apachectl restart command

Back to top

To import CA certificates for Apache Tomcat

  1. Convert key and certificate generated from OpenSSL into PKCS12 format (so we can convert to a JKS format with Java'skeytoollater, OpenSSL cannot convert to JKSandkeytoolcannotdirectly use the certificate and key)
    1. CA-signed Certificate

      • (Windows)

        openssl pkcs12 -export -out bmcsareports.p12 -inkey bmcsareports.key -in bmcsareports.pem -certfile ca-certs.pem -password pass:YOURPASSWORD

      • (UNIX)

        ./openssl pkcs12 -export -out bmcsareports.p12 -inkey bmcsareports.key -in bmcsareports.pem -certfile ca-certs.pem -password pass:YOURPASSWORD


    2. Self-signed Certificate

      • (Windows)

        openssl pkcs12 -export -out bmcsareports.p12 -inkey bmcsareports.key -in bmcsareports.pem -password pass:YOURPASSWORD

      • (UNIX)

        ./openssl pkcs12 -export -out bmcsareports.p12 -inkey bmcsareports.key -in bmcsareports.pem -password pass:YOURPASSWORD

  2. Convert the PKCS 12 keystore to a Java Keystore format.

    • (Windows)

      <bdssa install>\jre\bin\keytool -importkeystore -srckeystore bmcsareports.p12  -srcstoretype PKCS12 -srcstorepass YOURPASSWORD -alias <hostname> -deststorepass YOURPASSWORD -destkeypass YOURPASSWORD -destkeystore bmcsareports.jks

    • (UNIX)

      <bdssa install>/jre/bin/keytool -importkeystore -srckeystore bmcsareports.p12  -srcstoretype PKCS12 -srcstorepass YOURPASSWORD -alias <hostname> -deststorepass YOURPASSWORD -destkeypass YOURPASSWORD -destkeystore bmcsareports.jks
  3. Copy Keystore file in $BDS_HOME/tomcat/conf file.

  4. Update server.xml file in $BDS_HOME/tomcat/conf file with keystorefilename and its password.

    • (Windows)

      keystoreFile="C:\Program Files\BMC Software\BDSSA\tomcat\conf\bmcsareports.jks"
      keystorePass="YOURPASSWORD"

    • (UNIX)

      keystoreFile="/opt/bmc/BDSSA/tomcat/conf/bmcsareports.jks"
      keystorePass="YOURPASSWORD"
  5. Restart BDSSA Service.

Back to top

To configure Cognos to support CA certificates

  1. Copy the CA certificate (ca-chain.cert.pem) received from your CA to a secure location on the Cognos server.
    The certificate must be in the PEM format.
  2. On Windows 64-bit, obtain the IBM-shipped JRE from the Cognos Installer zip file, using the following steps:
    1. Extract COGNOS-BISVR-1021IF8WIN64.zip to a temporary location (such as C:\temp).
    2. Extract C:\temp\10_2_1_Interim_Fix_8\zipfiles\winx64h\jre-winx64h-gate-7.0.71.1.5-inst.tar.gz to another temporary location.
      From an NSH or Unix shell prompt, run 'tar xfvz jre-winx64h-gate-7.0.71.1.5-inst.tar.gz' to extract the file.
    3. From a command prompt, execute commands to set the JAVA_HOME variable, as in the following example (in which C:\jre is the temporary location to which you extracted the .gz file):
      cd %BDS_HOME%\portal\bin
      set JAVA_HOME=C:\jre\bin\jre\7.0

  3. Import the CA certificate by navigating to BDS_HOME\portal\bin on the command prompt by running the following command:

    Note

    The ThirdPartyCertificateTool command used in this step imports the CA certificate with the key store (jCAKeystore in this case) password if you specify the password. If -p is not included, NoPassWordSet is used as a default password. If you want to specify a different password, perform the following steps before executing this command:

    1. From the IBM Cognos Configuration, change the Signing key store password, the Encryption key store password, and the Certificate Authority key store password.

    2. Navigate to the BDSSAInstallationDirectory/portal/configuration directory, open the cogstartup_oracle.xml.tmpl or cogstartup_sqlserver.xml.tmpl file (depending on the database), and edit the passwords in the following directives: certificateAuthorityKeyFilePassword, signKeyFilePassword, and encryptKeyFilePassword.

    • (Windows)

      ThirdPartyCertificateTool.bat -T -i -r <CA_certFle> -k
      <BDS_HOME>\portal\configuration\signkeypair\jCAKeystore -p <password>

      For example:

      ThirdPartyCertificateTool.bat -T -i -r <CA_certFle> -k
      <BDS_HOME>\portal\configuration\signkeypair\jCAKeystore -p NoPassWordSet 
    • (UNIX)
      1. From the command prompt, set the JAVA_HOME variable to BDS_HOME/jre.

      2. Enter the following command:

        ThirdPartyCertificateTool.sh -T -i -r <CA_certFile> -k
        <BDS_HOME>/portal/configuration/signkeypair/jCAKeystore -p <password>

        For example:

        ThirdPartyCertificateTool.sh -T -i -r <CA_certFile> -k
        <BDS_HOME>/portal/configuration/signkeypair/jCAKeystore -p NoPassWordSet
  4. Restart Cognos.
  5. To verify that the configuration was successful, log on to the reports portal and ensure that it is populated with data.

Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*