Can I install a third-party SSL certificate in a CmapServer?

Answers to the questions most commonly asked about CmapTools and CmapServer.
Post Reply
cmapadmin
Site Admin
Posts: 797
Joined: Sat Dec 13, 2008 2:22 pm

Can I install a third-party SSL certificate in a CmapServer?

Post by cmapadmin »

Can I install a third-party SSL certificate, such as one by Thawte or Verisign, into the bundled Web server that comes with the CmapServer in order to ensure that users are accessing the Web-versions of Cmaps, folders, and resources stored there via a secure connection?

Yes. When the CmapServer is configured to use SSL for client/server connections, the default setting is to create a self-signed SSL certificate. Starting with CmapServer v4.11, for those who are instead planning to make use of a third-party SSL certificate that your school or university has (or is planning to) purchase, the following procedure has been tested to work:
  1. Install the CmapServer, making sure to select "Secure (SSL)" for the connection mode.
    • Open a terminal or command prompt and change directory to:

      cd /IHMC CmapServer/jre/bin/
      • Generate a private key by typing the following and then pressing "Enter":

        keytool -genkey -alias tomcat -keyalg RSA -keystore <domain_name>.kdb

        e.g. of a valid keystore database filename (only works for the ihmc.us domain): ihmc.us.kdb
        • Now you will be prompted to specify a password for your keystore. After doing so, you will be prompted to supply your first and last name.

          ***Important: Instead of supplying your first and last name at this prompt, supply the fully-qualified domain name (FQDN) of *your* website.

          E.g. of the components of an FQDN: cmap.ihmc.us
          • At the remaining prompts, you may enter relevant information upon reaching each new instruction until your keystore database file is finally created in this location:

            /IHMC CmapServer/jre/bin/<domain_name>.kdb

            ***Important: To minimize complexity, please choose to keep the same password for "<tomcat>" as you supplied in step #4 for the password of your keystore.
            • Generate the Certificate Signing Request (CSR) by typing the following and pressing "Enter":

              keytool -certreq -alias tomcat -keystore <domain_name>.kdb -file <any_name>.csr

              Note: Replace <domain_name> with the title of the *.kdb file you chose in step #3, and replace <any_name> with either whatever file title you choose, or with whatever filename might be required by your third-party SSL certificate vendor. You will be prompted for the same password you supplied in step #4.

              ***Important: Once finished, make sure to *not* delete the <domain_name>.kdb

              file and instead make a backup of this file so that it will be safe. That keystore database file will be essential later on in the procedure.
              • Give a copy of the <any_name>.csr file you created in step #6 to your third- party SSL certificate vendor by using the procedures outlined on their website, so that you will receive their "root" certificate file and the SSL certificate file that you purchased.

                ***Important: The certificates you receive from the third-party vendor *must* be in x.509 format, otherwise they will not successfully import into your keystore in the next step. One way to avoid complications is to not apply any formatting of the contents of *.cer files that you receive. The line breaks are important in the body of the certificates and must not be altered.
                • Rename the "root" CA certificate you received from the vendor to: root.cer ...and rename your purchased webserver SSL certificate to: <domain_name>.cer, e.g. of a valid webserver SSL certificate filename: ihmc.us.cer
                  • Copy and paste both certificate file from step #8 to this location:

                    /IHMC CmapServer/jre/bin/root.cer
                    /IHMC CmapServer/jre/bin/<domain_name>.cer
                    • Open a terminal or command prompt and change directory to:

                      cd /IHMC CmapServer/jre/bin/
                      • Type the following and press "Enter":

                        keytool -import -trustcacerts -keystore <domain_name>.kdb -alias root -file root.cer

                        When prompted, supply the password you chose in step #4. Note: Replace <domain_name> with the title of the *.kdb file you chose in step #3.
                        • Type the following and press "Enter":

                          keytool -import -trustcacerts -keystore <domain_name>.kdb -alias tomcat -file <domain_name>.cer

                          When prompted, supply the password you chose in step #4. Note: Replace <domain_name> with the title of the *.kdb and *.cer files you chose in steps #3 and #8 (respectively). The title should be the same for both files; only the three-letter extensions should be different.
                          • Open this file using a text editor (typical installation location):

                            /IHMC CmapServer/bin/serverconfig.txt
                            • Supply the fully-qualified domain name (FQDN) of the machine for the value of this parameter:

                              server.hostname=

                              Note: This FQDN *must* exactly match the FQDN specified in step #4 when you were generating the CSR.
                              • Supply the absolute path to the keystore database file for this parameter:

                                ssl.keystore=

                                Examples of the formatting for the value of the above parameter.
                                • Windows -- ssl.keystore=C\:\\Program Files\\IHMC CmapServer\\jre\\bin\\<domain_name>.kdb
                                • Linux -- ssl.keystore=/home/<user_name>/IHMC_CmapServer/jre/bin/<domain_name>.kdb
                              • Supply the password chosen in step #4 for the value of this parameter:

                                ssl.keystore.password=
                                • Save and exit the serverconfig.txt file, then launch the CmapServer. Now when accessing cmaps stored in your CmapServer via the Web, the "https:\\" will appear in the address bar, and the connections of HTTP clients that access your CmapServer's Web server will be encrypted. If your certificate is not expired, was obtained from a vendor who is in the list of trusted vendors for a client's Web browser, and the FQDN specified for the SSL certificate exactly matches that of the FQDN that appears in the address bar of an open Cmap in the client's Web browser, then the client should not receive any warnings when accessing Cmaps, resources, and folders on your CmapServer's Web server that was made secure using your third-party SSL certificate.
                                Post Reply