BMC Middleware and Transaction Management: V7 only - How to create a new keystore and certificate request using keytool shipped with Java?

Version 2
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    PRODUCT:

    BMC Middleware Monitoring


    COMPONENT:

    BMC Middleware and Transaction Management


    APPLIES TO:

    BMC Middleware Monitoring V7 BMC Middleware Management - Performance and Availability V7 BMC Middleware Management - Transaction Monitoring V7 BMC Middleware Management - Transaction Monitoring V7



    QUESTION:

    In case if you have problems to create the SSL keystore and certificate request, to renew the certificate or use an own certificate used by the Application Services for HTTPS connections to the product Web page this KB article was created to give you some additional details.

    Tasks like creating new certificates can’t be covered by BMC Support, you need to get an administrator from your public key infrastructure involved.  Since this task depends highly which kind of certificate authority is used to host the in-house public key infrastructure.

    This KB article was verified for versions 5.x – 7.x of the products mentioned above. In case if you are unsure or you run a more recent product version, please verify with BMC Customer Support, if the information from this article still applies. The steps mentioned in this article should be tested in a low priority test environment. If the wrong certificate template was used to generate a new certificate or you defined a wrong common name. you will no longer be able to access the product's web page by using HTTPS.

    The keytool command line utility is shipping with the Oracle Java Runtime Environment. If you need more details for keytool or Java in general please search for the related documentation provided by Oracle.

    Please back up any files before modifying them, so you have a way to revert to the last working configuration at any time.


    ANSWER:

     

    Please note that this is for BMTM v7 - this procedure has changed TMTM v8

    The below command examples assume that they are run on a Linux system. They should work without changes in any UNIX environment. In order for them to work on Windows, you need to replace the slashes ("/") in path names with backslashes ("\"). Also, on Windows, omit the dot-slash ("./") preceeding any commands.

      

    While the steps 1 - 4 are more general information on how to use keytool, steps 5 and onwards directly refer to the beforementioned BMC products.

      
    1. Create a keystore using keytool shipped with the services installation on the server in the <install_dir>/jre/bin folder with a private key.
      
    ./keytool -alias hostname -genkey -keyalg RSA -keystore hostname.jks

    When you run this command you will be asked a couple of questions, the questions about First and Last Name being the most imprtant ones. They reflect the Common Name Field and should match the hostname of the server which is used in your browser.
    For example, if you access the URL with https://myhostname:15004, the First Name and Last Name questions should be answered with "myhostname".
      

    When you run the command you will as well be asked for a key and keystore password. You need both passwords for OBF password encoding, before adding them to a configuration. The passwords are required for every application which needs to load the keystore or the public key (see #6 further down the instructions).

      
    2. Create a certificate request file, for https connection
      

    ./keytool -alias hostname -certreq -keyalg RSA -file hostname.csr -keystore hostname.jks

      

    The hostname.csr is the certificate request used to generate the certificate.

      
    3. Open the csr file generated by the last command with a text editor and copy everything between
      

    BEGIN NEW CERTIFICATE REQUEST-----
    ...
    ...
    END NEW CERTIFICATE REQUEST-----

      

    Submit this to your certificate authority ( CA ) to create a Web Server certificate. The type depends on the CA which is used.  Usually it is required to create an extended or enhanced certificate request on the CA and not a simple user certificate. For example on a Windows CA, the template for Web Server Certificates has to be used to generate the certificate. You could use a Base64 encoded certificate request, and you need to paste the text you copied from the csr file found between the BEGIN ... and END ... lines. Do not copy the BEGIN ... and END ... lines themselves.

      

    The certificate request then to be approved , usually this is a task for the public key infrastructure administrator. Then obtain the Web Server certificate you created from the csr file as well as the certificate from this certificate authority.

      
    4a. Import the certificate of the CA authority to the keystore.
      
    ./keytool -alias cacert -import -trustcacerts -file ca_certifcate.cer -keystore hostname.jks
      
    4b. Import the certificate for Web Server used to access the product page using HTTPS.
      
    ./keytool -alias hostname -import -trustcacerts -file hostname.cer -keystore hostname.jks
      
    5. Copy the keystore file (hostname.jks) from the <install_dir>/jre/bin to <install_dir>/jetty/webapps directory.
      
    6. Create encoded versions of the key and the keystore passwords.
      

    Navigate from command line in the <install_dir> directory and run:

      

    ./mqsusertool --encode –t OBF <your_keystore_password>
    ./mqsusertool --encode –t OBF <your_key_password>

      

    This will print encoded versions of the keystore and truststore passwords to the console. Use these in step 7.

      
    7.  Add or modify the configuration information in the product.
      

    Open the file <install_dir>/jetty/qpas.xml. Make sure to back up the file prior to making any changes.

      

    Locate the "SSL connector" section (search for "jetty.keystore") in the "qpas.xml" file and change the information as shown in the below example. You need to provide the name and location of the keystore as well as the encoded passwords for the key and the keystore. Use the encoded passwords generated in step 6. Do not use the passwords from the example.

      

    ...
                    <Set name="Keystore">
                        <SystemProperty name="jetty.keystore"
                            default="jetty/webapps/hostname.jks"/>
                    </Set>
                    <Set name="Password">
                        <SystemProperty name="jetty.keystore.password"
                            default="OBF:1fuk1kl61f9d1mrf1ldm1gu71ldw1mrn1f991klg1fuq"/>
                    </Set>
                    <Set name="KeyPassword">
                        <SystemProperty name="jetty.keystore.keypassword"
                            default="OBF:1fuk1kl61f9d1mrf1ldm1gu71ldw1mrn1f991klg1fuq"/>
                    </Set>
    ...

      

    Hint:
    It is recommended to place the new keystore into the same directory (<product dir>/jetty/webapps) the default keystore ("localhost.jks") already resides in. It is recommended to not use "localhost.jks" as the name of the new keystore, however, as a keystore with this name may get overwritten upon a product upgrade in which case all changes made to the keystore would be lost.

      
    8. Restart the product services.

     


    Article Number:

    000031493


    Article Type:

    FAQ/Procedural



      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles