Set secure agent connections

This topic provides an overview of SSL mutual authentication and explains how to set up mutual authentication for PulseUno servers and agents.

Overview

Secure Socket Layer (SSL) technology enables clients and servers to communicate securely by encrypting all communications. Data is encrypted before being sent, and decrypted by the recipient so that communications cannot be deciphered or modified by third parties. In PulseUno, you can enable a server to optionally communicate with its agents using SSL in mutual authentication mode.

In mutual authentication mode, communications are encrypted, but users are required to authenticate themselves by providing digital certificates.

A digital certificate is a cryptographically signed document intended to guarantee the identity of the certificate's owner. PulseUno certificates are self-signed.

When mutual authentication mode is active, PulseUno uses it for JMS-based server communication (via SSL from PulseUno to agents) and agent communication (via HTTPS from agents to PulseUno). In this mode, the PulseUno server provides a digital certificate to each agent, and each agent provides one to the server.

You can set up mutual authentication during server/agent installation, or activate it later.

Caution: Ensure that mutual authentication mode is turned on for both server and agents. Otherwise they will not connect. If one party uses mutual authentication mode, they must all use it.

Back to top

Configure mutual authentication

Prerequisite: Before configuring mutual authentication and exchanging keys, set the server and agent properties.

Follow these steps to enable mutual authentication for PulseUno servers and agents.

To set up mutual authentication:

  1. Verify that your PulseUno server and agents are not running.

  2. Run this command on the server to create a new key store and a private key for the server (if they do not exist):

    Copy code
    ${tomcatDir}/conf> keytool -genkey -alias <your-alias> -keyalg RSA -keystore <your-keystore-filename>

    Example: Use this example with the host name of a PulseUno server as the CN distinguished name:

    keytool -genkey -noprompt -alias pulse -keyalg RSA -keystore server-ssl.jks - keypass 123456 -storepass 123456 -dname "CN=<pulse-hostname>, OU=pulse, O=Company, L=Location, ST=PU, C=PU"

  3. To create a new Connector entry, add the following lines to the ${tomcatDir}/conf/server.xml file on the server:

    Copy code
    <Connector port="8443" scheme="https" secure="true" 
    SSLEnabled="true" clientAuth="false" 
    sslEnabledProtocols="TLSv1.2,TLSv1.1,TLSv1" sslProtocol="TLS" 
    keyAlias="pulse" keystoreFile="C:\Program Files\Micro Focus\common\tomcat\9.0\conf\server-ssl.jks" 
    keystorePass="123456" truststoreFile="C:\Program Files\Micro Focus\common\tomcat\9.0\conf\server-ssl.jks" 
    truststorePass="123456" ...
    </Connector>
    <!-- In this example keystore and truststore is the same file, but in general they could be separated -->
    <!-- if keystore has several aliases, a proper should be chosen. In this example "pulse" -->

    Do not use the same port number that is used in an existing Connector entry.

  4. Open the startup.properties file in the ${dataDir}/conf directory on the PulseUno server, for example:

    Windows C:\ProgramData\Micro Focus\PulseUno\conf
    UNIX/Linux /opt/microfocus/PulseUno/data/conf

    Add the following properties to the startup.properties file:

    Copy code
    pulse.activemq.protocol=ssl
    pulse.activemq.port=8447
    pulse.activemq.key.store.type=jks
    pulse.activemq.key.store.filename=C\:\\Program Files\\Micro Focus\\common\\tomcat\\9.0\\conf\\server-ssl.jks
    pulse.activemq.key.store.password=123456
    pulse.activemq.trust.store.type=jks
    pulse.activemq.trust.store.filename=C\:\\Program Files\\Micro Focus\\common\\tomcat\\9.0\\conf\\server-ssl.jks
    pulse.activemq.trust.store.password=123456
  5. Run this command on the server to create a server certificate:

    Copy code
    ${tomcatDir}/conf> keytool -export -keystore <your-keystore-filename> -alias <your-alias> -file <your-alias>.crt

    Example:
    ${tomcatDir}/conf> keytool -export -keystore server-ssl.jks -alias pulse -file pulse.crt

    The following message is displayed:

    **Certificate stored in file pulse.crt**

  6. Copy the exported pulse.crt certificate file to the following directory on the agent:

    ${pulseAgentDataDir}/conf

  7. Run this command to create a new key store and a private key for the agent (if they do not exist):

    Copy code
    ${pulseAgentDataDir}/conf> keytool -genkey -alias <agent_alias> -keyalg RSA -keystore <agent-store-file>.jks

    Example:
    ${pulseAgentDataDir}/conf> keytool -genkey -alias agent -keyalg RSA -keystore agent.jks -noprompt -keypass 123456 -storepass 123456 -dname "CN=<pulse-hostname>, OU=agent, O=Company, L=Location, ST=PU, C=PU"

  8. Open the config.properties file on the agent:

    ${pulseAgentDataDir}/config.properties

    Add the following properties:

    Copy code
    agent.auth.mode=MUTUAL
    # For mutual authentication between pulse and agents, key store and trust store should be configured:
    agent.auth.key.store.type=jks
    agent.auth.key.store.filename=C\:\\ProgramData\\Micro Focus\\Dimensions CM\\PulseAgent\\conf\\agent.jks
    agent.auth.key.store.password=123456
    agent.auth.trust.store.type=jks
    agent.auth.trust.store.filename=C\:\\ProgramData\\Micro Focus\\Dimensions CM\\PulseAgent\\conf\\agent.jks
    agent.auth.trust.store.password=123456
    # Location of the PulseUno application.
    pulse.base.url=https://<pulse-hostname>:8443/pulse
  9. Run this command in the agent's conf directory to import pulse.crt:

    Copy code
    ${pulseAgentDataDir}/conf> keytool -import -keystore agent.jks -alias pulse -file pulse.crt

    The following message is displayed:

    **Certificate was added to keystore**

  10. Run this command in the agent's conf directory to export the agent key as a certificate:

    Copy code
    ${pulseAgentDataDir}/conf> keytool -export -keystore agent.jks -alias <agent_alias> -file <agent_alias>.crt

    Example:
    ${pulseAgentDataDir}/conf> keytool -export -keystore agent.jks -alias agent -file agent.crt

    The certificate is stored in this file: <agent_alias>.crt

    Before you export an agent key, you need to generate it first.

  11. Copy the exported certificate file <agent_alias>.crt to this directory on the server:

    ${tomcatDir}/conf

  12. To import the <agent_alias>.crt file, run this command on the server in ${tomcatDir}/conf:

    Copy code
    keytool -import -keystore server-ssl.jks -alias <agent_alias> -file <agent_alias>.crt

    The following message is displayed:

    **Certificate was added to keystore**

  13. For additional agents, repeat from step 6.

  14. Start the PulseUno server and agents.

    If you installed the agent as a service, restart the service. Otherwise, shut down the agent using the agent control script and the shutdown parameter, and then start the agent.

Back to top

See also: