Authored by: Paul Oberly, Sr. Support Engineer – Micro Focus ADM – ALM at Orasi Software

Due to increasing concern over protecting servers from outside cyber threats, many organizations are pushing their Tool Administrators to enable secure access to their tools via SSL or HTTPS. MicroFocus ALM 12.xx and later uses an embedded Jetty server to present the ALM “web page”. Out of the box, ALM is not installed to deliver its page as a “secure” page and uses HTTP in the URL instead of HTTPS. This article explains how to setup ALM (and Jetty) to use the HTTPS (secure) URL and set to use an SSL certificate. This will help you to stay compliant with your company regulations regarding using secure servers for various tools you may be administrating, including ALM.

Before you begin

MicroFocus ALM 12.xx and later use an embedded Jetty server (9.1.4 or 9.4.19).  Jetty is a JAVA based web application server that reads its certificates out of a Java keystore. Keytool is used to create the keystore.  It is very important to use the keytool supplied with ALM to create the keystore file otherwise it may not be readable by the jetty server.

NOTE: You can use a tool like Portecle or KeyStore Explorer to create the keystore and add the cert in the same manner.

Setting up the ALM Servers for SSL

On the ALM sever, check for the following directory locations and adjust for your ALM installation.  These will be referenced later in this document. The default locations are as follows.

JAVA HOME

C:\ Program Files\HP\ALM\java\jre\bin

NOTE: Starting with ALM 12.6, you are expected to load your OWN version of Java, so this folder will be different, usually also under Program Files.

JETTY CONFIG

C:\ProgramData\HP\ALM\server\conf

NOTE: Depending on which version of ALM/QC you have, this folder may be “HP\ALM…” “HPE\ALM…”, or “Micro Focus\ALM…”.

IMPORTANT:  The following examples are using the default password of “changeit”.  You may continue to use it or in most situations replace it with a more robust password according to you organizations guidelines.

1. Create a keystore.

Creating the keystore also generates a self-signed certificate which can be used for initial testing of the server.  If using a certificate signed by a Certificate Authority the certificate issued will overwrite this certificate.

NOTE: We recommend placing the new keystore in a folder separate from ALM to avoid changes to it during future upgrades.  In this example, the certificate files are stored in C:\Certs.

a. Create a folder for the certs.

Use Windows explorer or command line to create a certificate folder “C:\Certs”.

b. Create the keystore and self-signed certificate.

Open a command window and navigate to your JAVA HOME directory.  Issue this command (better to type it in rather than copy/paste) to create the keystore and self-signed certificate.

keytool -genkey -alias server_cert -keyalg RSA -storepass changeit -keysize 2048 -keystore server.keystore

Keytool will then request the following information from you.  Fill in the values based on your environment.  Sample values have been provided in bold.

What is your first and last name?

[Unknown]: hpalm.ALMglobal.net (the FQDN of the server)

What is the name of your organizational unit?

[Unknown]: myUnit

What is the name of your organization?

[Unknown]: myOrg

What is the name of your City or Locality?

[Unknown]: King of Hill

What is the name of your State or Province?

[Unknown]: Pennsylvania

What is the two-letter country code for this unit?

[Unknown]: US

Is CN= hpalm.ALMglobal.net, OU= myUnit, O= myOrg, L= King of Hill, _

ST=Pennsylvania, C=US correct?

[no]: yes

Enter key password for <username>

(RETURN if same as keystore password):

2. Validate the keystore

The keystore will be created with a self-signed certificate.  You can validate the certificate by issuing the below command.  This shows the keystore is valid and allows you to check your certificate’s expiration date.

keytool -list -v -storepass changeit -keystore server.keystore

Keytool will echo back information about the keystore and the certificate it contains:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 1 entry

Alias name: server_cert

Creation date: Mar 11, 2013

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=hpalm.ALMglobal.net , OU=Unknown, O=myOrg, L=King of Hill, ST=Pennsylvania, C=US

Issuer: CN=hpalm.ALMglobal.net , OU=Unknown, O=myOrg, L=King of Hill, ST=Pennsylvania, C=US

Serial number: 513deb3e

Valid from: Mon Mar 11 10:33:34 EDT 2013 until: Wed Mar 11 10:33:34 EDT 2015

Certificate fingerprints:

MD5: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

SHA1: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

Signature algorithm name: XXXXX

Version: X

The keystore (server.keystore) file will be stored in the current folder (JAVA HOME).  Copy / move this file to the previously created C:\Certs directory.

If you are using Portecle or KeyStore Explorer, do the same thing:

1. Create a new keystore (JKS type)
2. Add a “keypair” (RSA, Key size 2048, version 3, SHA-256 with RSA, validity as long as you want, fill in CN, OU, etc. data as above – key value is the CN – it should be the server name.) When asked, name keypair something like “ALMsecure”, “ALM_cert”, or “servercert”.

3. Setting up the keystore.

 From here, you have two options:

Option 1 – Using a self-signed certificate

If you are going to be using a self-signed certificate skip this section and move directly to step 4.  A self-signed certificate was already generated when the keystore was created.

Option 2 – Installing certificates from your company’s Certificate Authority

Use the following command to generate a CSR (Certificate Signing Request) for your company’s Certificate Authority to sign.

keytool -certreq -alias server_cert -keyalg RSA -storepass changeit -file server_to_ca.csr –keystore C:\Certs\server.keystore

The csr (server_to_ca.csr) file will be stored in the current folder JAVA HOME.

Send the file “server_to_ca.csr” to your company’s Certificate Authority to sign digitally.  Your Certificate Authority will send a server certificate back (normally ending in .cer) that you import into the keystore. 

IMPORTANT: You should also receive the Certificate Authority’s intermediate certificate(s).  These will have to be imported prior to the server certificate. 

IMPORTANT: Place the certificate and intermediate certificate files in the C:\Certs directory.

This is a sample list of files for the MICROFOCUS ALM servers at this point in C:\Certs (using one root and two intermediate certificates):

server_to_ca.csr             – CSR SENT TO CA
server.keystore               – KEYSTORE
file1.cer.txt                       – CA ROOT CERT – MUST BE IMPORTED 1st

file2.cer.txt                       – CA INTERMEDIATE CERT – MUST BE IMPORTED 2nd
file3.cer.txt                       – CA INTERMEDIATE CERT – MUST BE IMPORTED 3rd
cert_from_ca.cer            – SERVER CERT RETURNED BY THE CA – MUST BE IMPORTED 4th

a. Import the certificates into the keystore.

Issue the following command to import the root certificate first:

keytool -storepass changeit -keystore C:\Certs\server.keystore -import -alias root_ca_cert -file file1.cer.txt -trustcacerts

NOTE: At the end of the import process, you will receive a confirmation.  Enter “yes” on the confirmation and check that the certificate has been added.

For example:

Owner: CN=XXX Enterprise Root CA 1, O=XXX
Issuer: CN=XXX Enterprise Root CA 1, O=XXX
Serial number: XXXXXXXXXXXXXXXXXXXXXXXXXXXX
Valid from: XXXX until: XXXX
Certificate fingerprints:
MD5:  XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
SHA1: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
Signature algorithm name: XXX
Version: 3< text excluded>Trust this certificate? [no]:  yes  < Type “yes” here.
Certificate was added to keystore    IMPORTANT:  Ensure that you receive confirmation message

Import the second file, Intermediate certificate 1:

keytool -storepass changeit -keystore C:\Certs\server.keystore -import -alias ca1_cert -file file2.cer.txt –trustcacerts

Import the third file, Intermediate certificate 2:

keytool -storepass changeit -keystore C:\Certs\server.keystore -import -alias ca2_cert -file file3.cer.txt -trustcacerts

Install the certificate file from the Certificate Authority:

keytool -storepass changeit -keystore C:\Certs\server.keystore -import -alias server_cert -file cert_from_ca.cer

IMPORTANT: This overwrites the self-signed certificate created previously.

IMPORTANT:  You could use a tool like Portecle or KeyStore Explorer to add your certs as “trusted certs” (in the same order as outlined here) as trusted certs. The server cert is imported as a “trusted cert” but is specified to import with the same alias as was used originally for the keypair.

b. Verify the keystore again.

Use the following to verify the contents of the keystore. When the keystore is verified this time, only one Private key and an entry for each trusted intermediate certificate should be seen:

keytool -storepass changeit -keystore C:\Certs\server.keystore -list

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 4 entries

ca2_cert, Apr 1, 2013, trustedCertEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

root_cert, Apr 1, 2013, trustedCertEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

server_cert, Apr 1, 2013, PrivateKeyEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

ca1_cert, Apr 1, 2013, trustedCertEntry,
Certificate fingerprint (MD5): XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:X

NOTE:  this could also be done by opening the keystore with a tool like Keystore Explorer and examining various certs contained.

c. Build the client trust store

The client trust store is found in the CA certs file.  It is basically the same process as building the server keystore.  The server certificate must be imported last this time instead.  Again, in this example, user received three intermediate certs from his CA.

keytool -storepass changeit -keystore C:\Certs\server.keystore –trustcacerts -import -alias root_ca_cert -file C:\Certs\file1.cer.txt

Note: Example Output – similar output will be generated for each of the trusted certs

Owner: CN=XXX Enterprise Root CA 1, O=XXX
Issuer: CN=XXX Enterprise Root CA 1, O=XXX
Serial number: XXXXXXXXXXXXXXXXXXXXXX
Valid from: XXXX until: XXX
Certificate fingerprints:
MD5:  XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
SHA1: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
Signature algorithm name: XXX
Version: 3

<text omitted>

Trust this certificate? [no]:  yes
Certificate was added to keystore

keytool -storepass changeit -keystore C:\Certs\ server.keystore  -trustcacerts -import -alias ca1_cert -file C:\Certs\file2.cer.txt

keytool -storepass changeit -keystore C:\Certs\ server.keystore  –trustcacerts -import -alias ca2_cert -file C:\Certs\file3.cer.txt

keytool -storepass changeit -keystore C:\Certs\ server.keystore  –trustcacerts -import -alias server_cert -file C:\Certs\cert_from_ca.cer

At the end of importing the trusted certs above, the server.keystore file is saved in “C:\Certs”.

4. Configure Jetty to use the keystore.

a. Open the start.ini file in the JETTY CONFIG directory and uncomment the jetty-ssl.xml and jetty-https.xml lines.

b. Edit the jetty-ssl.xml and input the keystore information.

NOTE: This is the way it looks “out of the box”.

Notice the parameterized build up of the path and name of the keystore.

Here,     KeyStorePath = TrustStorePath,

KeyStorePassword = KeyManagerPassword,

KeyStorePassword = TrustStorePassword

Also notice the example passwords out of the box are encrypted, “obfuscated”.  This is not necessary. Instead you can use a plain text password, initially to confirm it works before encrypting it.  For directions about Obfuscating / encrypting passwords, review the section titled “Password Obfuscation (encryption)” later in this document.

Or you could simplify the keystore path/name and password tags like this:

Simplified (and using plain text password):

c. OPTIONAL – edit the jetty-ssl.xml file and set the CipherSuites (rarely needed to change anything). It is a bit backward here – you include cipher suites you want to EXCLUDE, see Microfocus article KM01250751 – configuration varies by ALM version.

d. OPTIONAL – edit the jetty-ssl.xml file and set the SSL-TLS protocol restrictions. It is a bit backward here – you UNCOMMENT protocols you DON’T want (possible values: TLSv1, TLSv1.1, TLSv1.2, SSLv2, SSLv3).

e. OPTIONAL – edit the jetty-https.xml file and set the port at the bottom (default was 8443) if you wish to not have to enter the port number in the URL.

f. OPTIONAL – edit the jetty.xml and comment out the original “port 8080” connector to restrict non-secure access. Normally, we start with this uncommented so the initial run would do both HTTP (8080) as well as HTTPS/TLS.  It is a good test to have both at the same time and your users can fall back on HTTPS/8080 temporarily, then after getting HTTPS/TLS working, you can go back and comment out the HTTP/8080 part.

g. Start the ALM service — and Success.

Password Obfuscation (encryption)

If you wish to use an obfuscated/encrypted keystore password for use in the xml files, follow these directions.

Ref: https://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html

a. To do this you will need to use a utility located in the \server\lib directory:

For instance:

“C:\ProgramData\Micro Focus\ALM\server\lib\ jetty-util-9.4.19.v20190610.jar” (ALM 15)

“C:\ProgramData\HP\ALM\server\lib\ jetty-util-9.1.4.v20140401.jar” (ALM 12.6)

b. You will need to open a command prompt as an admin and run a command that looks like this (on an ALM12.6 server) to create an obfuscated password for “changeit”:

Java -cp “C:\ProgramData\HP\ALM\server\lib\jetty-util-9.1.4.v20140401.jar” org.eclipse.jetty.util.security.Password changeit

The jetty-util jar may have different numbers depending on the version but you should be able to adjust the above accordingly, also make sure there is a space after the closing quote and before the “org.eclipse.jetty.util.security.Password” part.  Additionally, if you used a password other than “changeit” you would specify that password at the end instead.

c. Right-click within the command window, then highlight what you want to copy, then press do Ctrl-C to copy (like the obscured password):

Our example:

OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0

d. Once you have run this you will need to copy the obfuscated password that was generated, it is the one preceded by “OBF:” (and no trailing whitespace) so copy that entire value and save it for later.

Links:

• https://wiki.eclipse.org/Jetty/Howto/CipherSuites
• https://wiki.eclipse.org/Jetty/Howto/Configure_SSL
• SSL/TLS Deployment Best Practices – This document provides practical recommendations about which cryptographic algorithms to use and which NOT to use and why.
• OWASP Testing Guide for Weak SSL/TLS Ciphers – Describes tools to use to verify which protocols and ciphers are accepted by the server
• Cipher Suites in Schannel – This article describes several cipher suites and their compliance to FIPS 140-2
• http://httpd.apache.org/docs/2.2/mod/mod_ssl.html