Description

A custom SSL configuration is helpful when you want to define your own security certificates and settings. It secures encrypted communication between a server and its clients. This approach differs from default or auto-generated SSL settings because you can specify your own keystore (which holds the server certificate and private key) and truststore (which holds trusted certificates or certificate authorities). 

For GMUS, a custom SSL configuration ensures encrypted, authenticated, and trusted data exchange. It secures communication between the GMUS REST Server and other systems in accordance with your organization's security requirements, which gives you more control over:

  • Which certificates are trusted and used for communication
  • How the server identifies itself to clients
  • The level of security and encryption used

This article explains how to configure a custom SSL setup for the GMUS REST Server. You will learn to create and reference a configuration file, generate keystore and truststore files, and run GMUS with SSL enabled. By following this guide, you will help establish secure, encrypted communication between the GMUS server and client applications.

In This Article


Creating the Configuration File

To add a custom SSL Configuration to GMUS, the following properties should be provided in a property file:

  • keystoreFile - This property should be set with the absolute path to the keystore file. The keystore file contains the server's certification, including its private key. 
  • truststoreFile - This property should be set to the absolute path of the truststore file. The truststore file contains certificates from other parties that are expected to be communicated with, or certificate authorities that are trusted to identify other parties
  • keystorePassword - This property should be set with the password for the specified keystore file
  • truststorePassword - This property should be set with the password for the specified truststore file


Refer to the sample config file below:

keystoreFile=/Users/aprilb/Downloads/KeyStore.jks
truststoreFile=/Users/aprilb/Downloads/truststore.jks
keystorePassword=abcd.1234
truststorePassword=abcd.1234


Running GMUS Rest Server with the Configuration File

To run the GMUS Server for secured requests with a custom SSL configuration, the command below should be run:

genrocket -gmussr <portNumber> -gmusp <configPath>


  • portNumber - Preferred port number where GMUS REST should run
  • configPath - Path to config file 


Sample: genrocket -gmussr 8070 -gmusp config.properties



When providing a custom SSL configuration, the following message above (in red box) will be shown when there is an API request. If not, please double-check the validity and correctness of the keystore and truststore configurations. 


Generating Keystore and Truststore Files

This guide explains how to create a Keystore (JKS) and Truststore for your Java applications using an SSL certificate and private key.


Prerequisites

Before starting, ensure you have:

  • The SSL certificate file (e.g., yourdomain.crt)

  • The corresponding private key file (e.g., private.key)

  • OpenSSL and Java (keytool) installed on your system

  • A secure location to store your keystore and truststore files


Step 1 - Create a PKCS12 (.p12) file

Combine your certificate and private key into a single PKCS12 file. This will later be imported into a Java Keystore.


openssl pkcs12 -export \
  -in yourdomain.crt \
  -inkey private.key \
  -out genrocket.p12 \
  -name genrocket


Explanation

  • -in → Your SSL certificate file

  • -inkey → The private key associated with your certificate

  • -out → The output PKCS12 file to be created (genrocket.p12)

  • -name → Alias name for the entry

You will be prompted to set an export password for the .p12 file — remember this password for the next step.


Step 2 - Create a Java Keystore (JKS)

Now, import the .p12 file into a Java Keystore.

keytool -importkeystore \
  -srckeystore genrocket.p12 \
  -srcstoretype PKCS12 \
  -destkeystore GRKeystore.jks \
  -deststoretype JKS \
  -alias genrocket

Explanation

  • -srckeystore → The source file (genrocket.p12)

  • -srcstoretype PKCS12 → Source type is PKCS12

  • -destkeystore → Output Java Keystore (GRKeystore.jks)

  • -deststoretype JKS → Destination format

  • -alias → Alias name (same as in previous step)


You'll be prompted for both the source keystore password (from Step 1) and a new password for the JKS file.


Step 3 - Create a Truststore

Import the SSL certificate into a new Java Truststore.

keytool -import -trustcacerts \
  -alias genrocket \
  -file yourdomain.crt \
  -keystore GRTrustStore.jks

Explanation

  • -trustcacerts → Marks this as a trusted CA certificate

  • -alias → Alias for the certificate

  • -file → Certificate file to import

  • -keystore → Truststore filename to create (GRTrustStore.jks)


You'll be prompted to create and confirm a Truststore password.