Enable HTTPS

• Before you begin
• Overview
• Passwords at a glance
• Important notes
• Step 1: Combine the certificate files
• Step 2: Package with OpenSSL (PKCS12)
• Step 3: Convert to Java Key Store (JKS)
• Step 4: Configure MCS
• Troubleshooting

Have the following ready before starting. Missing any of these mid-process is the most common cause of having to restart the tutorial.

• From your certificate authority (CA): either
  • a pair of certificate files (yourdomain.com.crt and IntermediateCA.crt), or
  • a single .pem file (yourdomain.com.pem).
• The matching private key (yourdomain.com.key) from the same CA request. This is required in either case.
• A Windows machine with administrator rights (to edit the PATH environment variable). These steps are done on Windows even if MCS itself runs on Linux. The resulting JKS file is portable.
• Access to the MCS server's filesystem to copy the final JKS file into /MCS root/data/ and edit https.ini.
• MCS version 10.1a or above. HTTPS support was introduced in this release.

Allow roughly 15–20 minutes end-to-end, plus any time needed to install OpenSSL and a JDK if they are not already on the machine.

You will chain four files together: the CA-issued certificates and your private key are bundled into a PKCS12 archive, converted into a Java Key Store, and then referenced by an MCS config file.

Support: if you hit an issue, check the troubleshooting section or send an email.

The same password is used at four prompts across Steps 2–4. Choosing it once and re-using it everywhere is the simplest path; mismatches are the most common cause of HTTPS failing to come up at runtime.

Platform: these steps are documented on Windows. The resulting JKS file is portable and works with MCS on both Linux and Windows. Performing the build on Windows is recommended even if MCS is installed on Linux.

A valid SSL certificate provided by the issuing certificate authority is required. It will normally consist of two files, for example yourdomain.com.crt and IntermediateCA.crt.

Combine the two .crt files:

1. Create a folder on the Windows desktop (or other suitable location).
2. Place both certificate files inside that folder.
3. Open a Windows command prompt and cd into the folder.
4. Run:

   type yourdomain.com.crt IntermediateCA.crt > certs.txt

   Certificate order matters: the end-entity certificate (your domain) must come first, followed by the intermediate CA.
5. Verify that certs.txt was created in the same folder.

Combining certificate files

Leave the command window open for use in Step 2.

This step requires OpenSSL for Windows (scroll to the "Download Win32 OpenSSL" section on that page). OpenSSL 3.x is current; the command syntax below works on both 1.1.1 and 3.x.

1. Download and install the full OpenSSL installer for your architecture (32-bit or 64-bit). Skip if already installed.
2. Locate the bin directory in the install folder. On 64-bit systems this is typically drive:\OpenSSL-Win64\bin.
3. Add that bin directory to the Windows PATH environment variable so openssl resolves from your command prompt.
4. Run the command that matches your input files:

   CRT method (using the combined certs.txt from Step 1):

   openssl pkcs12 -export -inkey yourdomain.com.key -in certs.txt -out certs.pkcs12

   PEM method (if your CA provided a .pem):

   openssl pkcs12 -export -inkey yourdomain.com.key -in yourdomain.com.pem -out certs.pkcs12

5. When prompted for "Enter Export Password:", choose an alphanumeric password of 8–16 characters and re-enter it to confirm. Remember this password. You will use it at three more prompts (see Passwords at a glance).
6. Verify that certs.pkcs12 was created in the same folder.

Creating the PKCS12 file with OpenSSL

Leave the command window open for use in Step 3.

This step requires the Java keytool utility, which ships with any standard JDK distribution.

1. If a JDK is not already installed, download and install a current LTS release. Any standard distribution is supported, for example Eclipse Temurin, Amazon Corretto, Azul Zulu, Microsoft Build of OpenJDK, or Oracle JDK.
2. Add the JDK bin directory to the Windows PATH environment variable.
3. Run:

   keytool -importkeystore -srckeystore certs.pkcs12 -srcstoretype PKCS12 -destkeystore certs.jks -deststoretype JKS

4. You will be prompted three times. Enter the same password you chose in Step 2 at each prompt (see Passwords at a glance):
   • For "Enter destination keystore password:", enter your Step 2 password.
   • For "Re-enter new password:", enter the same again.
   • For "Enter source keystore password:", enter the same again (this is the existing PKCS12 password).
   A typical run looks like this:

V:\SSL Certs>keytool -importkeystore -srckeystore certs.pkcs12 -srcstoretype PKCS12 -destkeystore certs.jks -deststoretype JKS
Enter destination keystore password:
Re-enter new password:
Enter source keystore password:
Entry for alias 1 successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

5. keytool will typically print: "Warning: The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12...". This is expected and safe to ignore. MCS currently requires JKS. See Important notes.
6. Verify that certs.jks has been created in the same folder, ready for use in Step 4.

1. On the MCS server, navigate to the /MCS root/data/ directory. The same JKS file works on both Linux and Windows installations.
2. First-time setup only: rename example-https.ini to https.ini.
3. Copy the certs.jks file from Step 3 into /MCS root/data/.
4. Edit https.ini and set:
   • SSLKeyStoreFileName to the certs.jks filename.
   • SSLPassword to the password you chose in Step 2 (see Passwords at a glance).

https.ini configuration

chown mcs:mcs certs.jks https.ini
chmod 600 certs.jks https.ini

Stop and restart MCS to load the new certificate. Once enabled, only HTTPS traffic will be authorized and any login request initiated over HTTP will be automatically redirected to HTTPS. Port 80 remains open for those redirects and for high-performance MCS hardware/software satellites that rely on it for test accuracy.

• Passwords used throughout the process must match exactly and contain only letters and numbers (MCS-specific constraint: special characters are not currently supported by the https.ini parser).
• Verify that the password specified in the https.ini file matches the one used for the certificate JKS file. The destination (JKS) password set in Step 3 and the source (PKCS12) password set in Step 2 must also match each other.
• Ensure that the JKS filename specified in https.ini is correct and that the file exists in the /MCS Root/data/ directory.
• On Linux, confirm that certs.jks and https.ini are readable by the user the MCS service runs as. If you tightened permissions with chmod 600, the files must be owned by that user.
• Confirm that the installed JDK is a current stable LTS release. Issues have been reported with early access (EA) and release candidate (RC) versions. Any standard OpenJDK distribution (Temurin, Corretto, Zulu, Microsoft, Oracle) is supported.

Detecting the JDK type installed

Check the Java version:

java --version

If the output does not explicitly state EA or RC, check the package manager:

Debian / Ubuntu:

apt list --installed | grep openjdk

Red Hat / Fedora:

dnf list installed | grep java

Arch Linux:

pacman -Q | grep jdk

Some Java distributions (including OpenJDK) store version details under /usr/lib/jvm/:

ls -l /usr/lib/jvm/

• Check the MCS console log located in /MCS Root/logs/. If MCS encounters an issue verifying the certificate, details will be recorded there.