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.

Note

The UNIX instructions are applicable only for deployments with the Oracle database.

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 a signed certificate file (for example, ca_cert.crt).

To configure Apache to support CA certificates

  1. If BMC BladeLogic Decision Support for Server Automation is not configured for SSL communication using https, run the following command:

    set sslon


    This command configures Apache and Cognos to support SSL communication. You must restart the Apache server and Cognos to verify that the reports are accessible.

  2. Copy the certificate private key file (bmcsareports.key), and the CA certificate file (ca_cert.crt) 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.

  3. Navigate to the BDS_HOME\webserver\conf 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_cert.crt"
      .

  4. Restart the Apache server.

    Warning

    After configuring Apache for CA certificate support, you must not run the set sslon or the set sslport commands. These commands undo the configuration changes made for CA certificate support.

To configure Cognos to support CA certificates

  1. Copy the CA certificate (ca_cert.crt) received from your CA to a secure location on the Cognos server.
    The certificate must be in the PEM format.
  2. 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 -java:local -T -i -r <CA_certFle> -k
      <BDS_HOME>\portal\configuration\signkeypair\jCAKeystore -p <password>

      For example:

      ThirdPartyCertificateTool.bat -java:local -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 -java:local -T -i -r <CA_certFile> -k
        <BDS_HOME>/portal/configuration/signkeypair/jCAKeystore -p <password>

        For example:

        ThirdPartyCertificateTool.sh -java:local -T -i -r <CA_certFile> -k
        <BDS_HOME>/portal/configuration/signkeypair/jCAKeystore -p NoPassWordSet
  3. Restart Cognos.
  4. To verify that the configuration was successful, log on to the reports portal and ensure that it is populated with data.
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Kyle Sorg

    Under "To create a CSR request using OpenSSL"

    Step 7 references using bmcsareports_new.key
    "Run the following command to create a CSR by using the private key (bmcsareports_new.key) that you created in step 3"

    but the example code references the RSA key. 

    "

    ./openssl req -new -key bmcsareports.key -out bmcsareports_new.csr -config /opt/bmc/bladelogic/NSH/share/openssl.cnf"

     This is was a bit misleading.  Step 7 should replace bmcsareport_new.key with bmcsareports.key

     

    May 11, 2016 03:25
    1. Abhilasha Garg

      Thanks Kyle. We've corrected the step.

      May 13, 2016 04:21
      1. Kyle Sorg

        There is a second instance of this under "To configure Apache to support CA certificates"

        First it states "Copy the certificate private key file (bmcsareports_new.key)"

        however it states the following when updating the file:

        SSLCertificateKeyFile "C:/Program Files (x86)/BMC/BDSSA/webserver/conf/bmcsareports.key".

        Jun 02, 2016 12:40
        1. Yechezkel Schatz

          Fixed. Thanks, Kyle.

          Aug 22, 2016 10:50
  2. Kyle Sorg

    This document states that the user should update the SSLCACertificateFile in httpd-ssl.conf with the issue CA.  This is incorrect. 

    SSLCertificateFile (without CA) should be updated with the CA.

    SSLCertificateKeyFile should be updated with the private key.

    SSLCACertificateFile should not be modified.  This was our CA Chain for CAC/PKI authentication. (as a side note PKI/CAC authentication does not properly describe this step either)

    Jun 02, 2016 04:01
    1. Yechezkel Schatz

      I corrected the step. Please review it and let me know if it seems right now. Thanks, Kyle.

      Aug 22, 2016 10:52
  3. Kyle Sorg

     I believe that the use of -java:local is old this no longer works.  I had to remove this entry in order to import the CA.

    ThirdPartyCertificateTool.sh -java:local -T -i -r <CA_certFile> -k
    <BDS_HOME>/portal/configuration/signkeypair/jCAKeystore -p NoPassWordSet
    In addition the docs states to review the cogconfig_response.csv this does not exist on RHEL.  However cogconfig_default.log is.  There are also cogserver.logs that can be review under <BDSSAHome>/logs
    Jun 03, 2016 09:26
    1. Yechezkel Schatz

      I removed -java:local in the documentation for BDSSA versions 8.7 and later. I was told that it is still necessary in versions 8.6 and earlier. If this doesn't match your experience, let me know and I'll check again.

      I totally changed the step for verifying a successful configuration, so cofconfig_response.csv is no longer mentioned.

      Aug 22, 2016 10:54