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.

For using third-party CA certificates, the general steps are:

1. Create a certificate signing request (CSR) using OpenSSL and send the CSR to CA. CA returns the signed authority, along with the CA certificate. For instructions, see To create a CSR request using OpenSSL.
2. Configure Apache to support CA certificates. For instructions, see To configure Apache to support CA certificates.
3. Configure IBM Cognos to support CA certificates. For instructions, see To configure Cognos to support CA certificates.

Before you begin

1. Obtain the openssl utility and unzip it into a local directory. 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=<localDir>\openssl.cnf

     For example:

     SET OPENSSL_CONF=D:\temp\openssl.cnf

   • (UNIX)

     export OPENSSL_CONF=<localDir>/openssl.cnf

     For example:

     export OPENSSL_CONF=/tmp/openssl.cnf 

To create a CSR request using OpenSSL

1. Log on to a computer where Network Shell is installed.
2. From the command prompt, navigate to the following directory:
   • (Windows) BDSSAInstallationDirectory\webserver\bin
   • (UNIX) BDSSAInstallationDirectory/webserver/bin

3. Use the following command to create an RSA private key that is Triple-DES encrypted. This command creates the private key in the directory from where you run the command.

   • (Windows)

     openssl genrsa -des3 -out <namePrivateKey>.key 2048

     For example:

     openssl genrsa -des3 -out bmcsareports_new.key 2048

   • (UNIX)

     ./openssl genrsa -des3 -out <namePrivateKey>.key 2048

     For example:

     ./openssl genrsa -des3 -out bmcsareports_new.key 2048

   In the above command:

   • -des3 encrypts the private key with the des3 cipher before outputting it.

   • namePrivateKey indicates the name with which private key will be generated.

   • 2048 indicates the size of the private key to generate in bits.

   Note

   If the above commands result in the following error:
   openssl: error while loading shared libraries: libssl.so.1.0.0: cannot open shared object file: No such file or directory

   Then create links for following files as shown below from /$BDS_HOME/webserver/bin:

   # ln -s /data1/bmc/BDSSA/webserver/lib/libssl.so.1.0.0  libssl.so.1.0.0

   # ln -s /data1/bmc/BDSSA/webserver/lib/libcrypto.so.1.0.0 libcrypto.so.1.0.0

4. Create and confirm the pass phrase for the private key.

5. After the private key is created, run the following command:

   • (Windows)

     openssl rsa -in bmcsareports_new.key -out bmcsareports.key

   • (UNIX)

     ./openssl rsa -in bmcsareports_new.key -out bmcsareports.key

   In the above command, bmcreports_new.key is the private key that you created in step 3.

6. Enter the pass phrase that you created in step 4.

7. Run the following command to create a CSR by using the private key (bmcsareports.key) that you prepared in step 5:

   • (Windows)

     openssl req -new -key bmcsareports.key -out bmcsareports.csr -config <localDir>\openssl.cnf

     For example:

     openssl req -new -key bmcsareports.key -out bmcsareports.csr -config D:\temp\openssl.cnf

   • (UNIX)

     ./openssl req -new -key bmcsareports.key -out bmcsareports.csr -config <localDir>/openssl.cnf

     For example:

     ./openssl req -new -key bmcsareports.key -out bmcsareports.csr -config /tmp/openssl.cnf

     
     

   bmcsareports.csr is the output file containing CSR. The above command sends a request to the CA to generate the certificate in PEM (Base-64 encoded ASCII) format, which is the format required by Apache and Cognos to support CA certificates.

8. Enter the pass phrase that you created in step 4.
9. 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
10. Send the CSR file (bmcsareports.csr) to a CA for signing using one of the following methods. 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.
    
    • Have the CSR signed by a commercial CA like Verisign or Thawte. This process usually requires you to post the CSR into a web form, pay for the signing, and await the signed certificate. For more information about commercial CAs see:
      • Verisign: http://digitalid.verisign.com/server
      • Thawte Consulting: http://www.thawte.com/certs/server/request.html
      • CertiSign Certificadora Digital Ltd: http://www.certisign.com.br
      • IKS GmbH: http://www.iks-jena.de/produkte/ca/
      • Uptime Commerce Ltd: http://www.uptimecommerce.com
      • BelSign NV/SA: http://www.belsign.be
    • Use your own CA and get the CSR signed by this CA.
      The result is then a real certificate that can be used for Apache and Cognos.

To import CA certificates for Apache Tomcat

1. Convert key and certificate generated from OpenSSL into PKCS12 format.

   • (Windows)

     \opt\bmc\BDSSA\webserver\bin\openssl pkcs12 -export -in <Certificate in pem> -inkey <KEY> -out <outputfile.p12> -name <hostname> -passin <pass:password> -passout <pass.password>

     For example:

     \opt\bmc\BDSSA\webserver\bin\openssl pkcs12 -export -in bdssareports.pem -inkey bdssareports.key -out srv-abc-016201.p12 -name srv-abc-016201 -passin pass:password -passout pass:password

   • (UNIX)

     /opt/bmc/BDSSA/webserver/bin/openssl pkcs12 -export -in <Certificate in pem> -inkey <KEY> -out <outputfile.p12> -name <hostname> -passin <pass:password> -passout <pass.password>

     For example:

     /opt/bmc/BDSSA/webserver/bin/openssl pkcs12 -export -in bdssareports.pem -inkey bdssareports.key -out srv-abc-016201.p12 -name srv-abc-016201 -passin pass:password -passout pass:password

2. Create Keystore.

   • (Windows)

     \opt\bmc\BDSSA\jre\bin\keytool -importkeystore -srckeystore <outputfile.p12>  -srcstoretype PKCS12 -srcstorepass <password> -alias <hostname> -deststorepass <password> -destkeypass <password> -destkeystore <keystorename.jks>

     For example:

     \opt\bmc\BDSSA\jre\bin\keytool -importkeystore -srckeystore srv-abc-016201.p12 -srcstoretype PKCS12 -srcstorepass password -alias srv-abc-016201 -deststorepass password -destkeypass password -destkeystore srv-abc-016201-keystore.jks

   • (UNIX)

     /opt/bmc/BDSSA/jre/bin/keytool -importkeystore -srckeystore <outputfile.p12>  -srcstoretype PKCS12 -srcstorepass <password> -alias <hostname> -deststorepass <password> -destkeypass <password> -destkeystore <keystorename.jks>

     For example:

     /opt/bmc/BDSSA/jre/bin/keytool -importkeystore -srckeystore srv-abc-016201.p12 -srcstoretype PKCS12 -srcstorepass password -alias srv-abc-016201 -deststorepass password -destkeypass password -destkeystore srv-abc-016201-keystore.jks

3. Copy Keystore file in $BDS_HOME/tomcat/conf file.

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

   • (Windows)

     keystoreFile="\opt\bmc\BDSSA\tomcat\conf\srv-abc-016201-keystore.jks"
     keystorePass="password"

   • (UNIX)

     keystoreFile="/opt/bmc/BDSSA/tomcat/conf/srv-abc-016201-keystore.jks"
     keystorePass="password"

5. Restart BDSSA Service.

To configure Apache 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, open the file and check that contents of the file is enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" tags.

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".

   2. If the CA certificate 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".

   3. If the CA certificate is available, search for  SSLCertificateFile and uncomment the line containing this entry, and specify the full path of the CA certificate file. For example:


      SSLCertificateFile "C:/Program Files (x86)/BMC/BDSSA/webserver/conf/bmcsareports.pem".

3. Restart the Apache server.

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.
   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.