Enable HTTPS

• Notes
• Overview
• Step 1: Create the combined certificate file
• Step 2: Install and use OpenSSL to package the combined certificate file
• Step 3: Create the Java compatible Key Store File (.JKS) to be used by MCS
• Step 4: Configure MCS so it can find the JKS file
• Troubleshooting

HTTPS support in MyConnection Server (MCS) requires version MCS 10.1a or above.

As a best practice, this tutorial documents 4 steps to create the MCS certificate file using the Windows platform. The certificate file can be transferred and used with MCS on both Linux and Windows platforms.

Performing these steps on Windows is recommended even if MCS is installed on Linux.

The 4 steps to enabling HTTPS/SSL in MCS are as follows:

1. Create a combined SSL certificate that was provided by a certificate authority for use with MCS.
2. Convert the certificate created in step 1 to an OpenSSL PKCS file.
3. Convert the PKCS file into a Java Key Store (.jks) file for use by MyConnection Server.
4. Configure MCS to locate and use the .jks file.

A valid SSL certificate provided by the issuing certificate authority is required for this step. The certificate must consist of 2 files, for example yourdomain.com.crt and intermediateCA.crt.

The two certificate (.crt) files need to be combined together to create a single file as follows:

1. Create and name a folder on the Windows desktop or other suitable location.
2. Place the two certificate files to be combined in the named folder.
3. Open a Windows command prompt and navigate to the named folder directory.
4. Enter the command: type yourdomain.com.crt IntermediateCA.crt > certs.txt to create the combined file.

Combining certificate files

Leave the command window open for continued use in Step 2.

This step requires the OpenSSL package for Windows (scroll down to the Download Win32 OpenSSL section for download links) in order to convert the combined certificate file to the OpenSSL PKCS file format.

1. If not already installed, download and install the full OpenSSL installer appropriate for the processor architecture required (32 bit or 64 bit).
2. Once installed, locate the bin directory in the install folder. For 64-bit platforms this should be drive:\OpenSSL-Win64\bin.
3. Add the bin directory path to the Windows PATH environment variable to allow OpenSSL to process from the open command prompt window.
4. Enter the appropriate command line:

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

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

Creating PKCS12 file with OpenSSL

5. When the password prompt appears, enter a strong alphanumeric password (8 to 16 characters) and continue. This password will be required in Step 3.
6. Verify that the OpenSSL certs.pkcs12 file has been created.
7. Leave the command window open for continued use in Step 3.

This step requires the Oracle Java keytool utility.

1. If not already installed, download and install the Oracle Java JDK.
2. Add the JDK bin directory path to the Windows PATH environment variable.
3. Enter the command line: keytool -importkeystore -srckeystore certs.pkcs12 -srcstoretype PKCS12 -destkeystore certs.jks -deststoretype JKS

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

4. When requested, enter a strong alphanumeric password for the destination (8 to 16 characters) and re-enter the same password for confirmation when prompted.
5. When prompted for the keystore password, enter the same password used when creating the certs.pkcs12 file in Step 2, item 5. If these do not match, the certificate will be denied at run time.
6. The Java certs.jks file should have been created for use in Step 4.

1. Navigate to the /MCS root/data/ directory on the system where MCS has been installed. The key is valid to be used on Linux or Windows platforms.
2. For first time implementation, rename the example-https.ini file to https.ini.
3. Copy the certs.jks file created in Step 3 to the /MCS root/data/ directory.
4. Edit the https.ini file and:
   • Amend the SSLKeyStoreFileName setting to reference the certs.jks file name.
   • Amend the SSLPassword setting to reference the password that was entered in Step 2, item 5.

https.ini configuration

The certificate configuration process is now complete.

MCS should be stopped and restarted to enable the SSL certificate. If a restart does not enable HTTPS, there may be an issue with the cert or JKS. Please review the troubleshooting section below.

Once enabled, only HTTPS traffic will be authorized and any user login requests initiated over HTTP will be automatically redirected to HTTPS. Port 80 is still required for redirects and support of high performance MCS hardware and software satellites which will continue to be authorized to ensure test accuracy.

• Passwords used throughout the process must match exactly and contain only letters and numbers. Special characters are not allowed.
• Verify that the password specified in the https.ini file matches the one used for the certificate JKS file.
• Ensure that the JKS filename specified in https.ini is correct and that the file exists in the /MCS Root/data/ directory.
• Confirm that the installed Oracle Java JDK is the latest stable release. Issues have been reported with early access (EA) and release candidate (RC) versions.

Detecting the JDK Type Installed

Run the command below to check the Java version:

java --version

If this 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 (like OpenJDK) store version details in /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.