Skip to main content

Service encryption

Service traffic encryption is designed to enhance the security of exchanges and to protect user privacy against attacks carried out from networks. In this section, we show you how to configure it for your Genesis applications.

Genesis supports SSL / TLS for client->server and process->process communications where needed.

In order to achieve this, we will create a certificate and a Java Keystore. A file with the extension .jks serves as a keystore. It can store keys such as public key certificates, authorization certificates or private keys.

Generating and installing certificates​

You will need signed certificates to encrypt service traffic.

Here are some instructions on how to create a Java keystore file.

Type the keytool command all on one line:

java-home/bin/keytool -genkey -alias server-alias -keyalg RSA -keypass changeit -storepass changeit -keystore keystore.jks

When you press Enter, keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code.

Type the server name in response to keytool’s first prompt, in which it asks for first and last names.

When you run the example applications, the host (server name) specified in the keystore must match the host identified in the javaee.server.name property specified in the file build.properties.

Generating a self-signed keystore and respective certificate (optional)​

This step is only required if you are using a self-signed certificate due to the absence of one issued by a proper trusted root authority.

$ keytool -genkey -keyalg RSA -keysize 2048 -alias selfsigned -storepass Password1233 -keystore keystore.jks -ext SAN=dns:genesisserv1,dns:genesisserv1.ad.genesis.global,dns:genesisserv2,dns:genesisserv2.ad.genesis.global,dns:genesisserv3,dns:genesisserv3.ad.genesis.global,dns:genesisserv4,dns:genesisserv4.ad.genesis.global,ip:193.144.16.43

What is your first and last name?
    [Unknown]:  Fred Bloggs

What is the name of your organizational unit?
    [Unknown]:  IT

What is the name of your organization?
    [Unknown]:  Genesis Global Technology Ltd

What is the name of your City or Locality?
    [Unknown]:  London

What is the name of your State or Province?
    [Unknown]:  Greater London

What is the two-letter country code for this unit?
    [Unknown]:  GB

Is CN=Fred Bloggs, OU=IT, O=Genesis Global Technology Ltd, L=London, ST=Greater London, C=GB correct?
    [no]:  yes

Enter key password for <selfsigned>
    (RETURN if same as keystore password):

Assuming no problems with privileges, you will now have a certificate called "selfsigned" with a private key using the same password as the keystore password e.g. Password123.

In our example, this certificate can be found at: /home/exmon/keystore.jks

Please note, however, that this certificate should be stored in another directory outside the application.

The keystore (.jks) is, in a way, the private key to be used in the two-way authentication in the SSL protocol. As such, you need to use it to generate the certificate that has to be installed by the target computers, or to be loaded by the processes that the application intends to communicate with.

$ keytool -export -alias mykey -file certificate.crt -keystore keystore.jks

Installing TLS certificate in different environments​

Linux​

This varies according to the distribution being used. In Ubuntu:

$ cp certificate.crt /usr/local/share/ca-certificates/

$ sudo update-ca-certificates

Windows​

Right-click on certificate.crt and select 'Install Certificate'. On 'Place all certificates in the following store', select 'Trusted Root Certification Authorities'.

Securing Genesis processes​

First, you must enable processes to communicate via SSL. In order to do this, we must ensure that the secure element is set to "true". Without this, your application would send communications along with any non-encrypted HTTP requests to your domain.

All Genesis modules are defined inside the service definition files. To allow for service-to-service encryption you must make this change in the *-service-definitions.xml files.

<configuration>
  <service host="localhost" name="POSITION_DATASERVER" port="11000" secure="true"/>
  <service host="localhost" name="POSITION_REQUEST_SERVER" port="11001" secure="true"/>
  <service host="localhost" name="POSITION_EVENT_HANDLER" port="11002" secure="true"/>
  <service host="localhost" name="POSITION_CONSOLIDATOR" port="11003" secure="true"/>
  <service host="localhost" name="POSITION_FGW" port ="11004" secure="true"/>
  <service host="localhost" name="POSITION_FGW_STREAMER" port ="11005" secure="true"/>
  <service host="localhost" name="POSITION_FGW_STREAMER_CLIENT" port ="11006" secure="true"/>
</configuration>
warning

The global-service-definitions.xml file and the processes.xml file are erased and re-generated every time you run genesisInstall. (You should never change these files, because any changes will be lost the next time you run genesisInstall.)

Therefore, it is essential that you set the service-definitions.xml file this way for every service or module for which you want to enable SSL.

Setting the TLS settings for all processes by default​

Open the genesis-system-definitions.xml file and edit the values for DefaultKeystoreLocation, DefaultKeystoreLocation and DefaultCertificate.

For example:

<!-- Required if the processes are to communicate through SSL -->
<Item name="DefaultKeystoreLocation" value="/home/exmon/keystore.jks" />
<Item name="DefaultKeystorePassword" value="Password123" />
<Item name="DefaultCertificate" value="/home/exmon/certificate.crt" />

These will be used by all processes to communicate with encrypted processes or to accept connections if they are encrypted themselves.

Setting the TLS settings for each individual process​

tip

You can have different processes secured via different certificates, if required.

This setting is used if the develop wants to override the defaults established above for a specific process.

Open the configuration file for the process (as defined in <product>-processes.xml). Make sure it has the following settings:-

<authManager>
  <settings>
    <messaging>
      <keyStoreLocation>/home/poc/keystore.jks</keyStoreLocation>
      <keyStorePassword>Password123</keyStorePassword>
    </messaging>
  </settings>
</authManager>

Once the files have been saved, run genesisInstall. When the processes starts again, it will be secure.

GUI​

To enable the GUI to connect securely, edit the %ProgramData%\\Genesis\\exmon\\Rel\\Config\\PrimaryServiceConfig.xml setting encrypted to true.

Example​

<?xml version="1.0"?>
<primary_service xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <encrypted>true</encrypted>
  <hosts>
    <host name="genesisserv4.ad.genesis.global" port="8001" />
  </hosts>
</primary_service>

Note: With encryption, if you are using a self-signed certificate, you must install the certificate.crt in the target machine's operating system as a trusted root CA.

Web front-end​

Install the certificate.crt in the target machine's operating system as a trusted root CA. That is all you need to do.