Search
SupportConsoleDevelopersStart a trialContact

3. Configuring SSL Connections for Server-Agent Communication

download PDF
By default, the JBoss ON server and JBoss ON agents talk to each other in the clear, meaning all communications traffic is unencrypted and no authentication is performed on either end.
Running servers in the clear, particularly since JBoss ON can perform configuration changes on some types of resources, can have security considerations for your network. JBoss ON should only be run without encryption or authentication if JBoss ON is being tested or if all JBoss ON servers and agents are deployed on a fully secured network, with access limited by a firewall or VPN and restricted to trusted personnel.
JBoss ON uses SSL/TLS to secure connections between agents and servers in two separate ways:
  • Encryption specially encodes the data sent between agents and servers during a session.
  • Authentication uses SSL server and client certificates to verify the identity of an agent before it connects to a server, and vice versa.

Note

There is a basic authentication mechanism employed by the server in which it assigns security tokens to its agents which are used to identify and "authenticate" registered agents. This token mechanism should not, however, be considered a strong authentication scheme for the purposes of protecting your JBoss ON network from infiltration.
Setting up encryption is very simple; it only requires enabling the proper transport mechanism between servers and agents. This prevents an attacker from intercepting communications or data between a legitimate JBoss ON server and a legitimate JBoss ON agent, by sniffing data or setting up a man-in-the-middle attack.
Authentication adds another layer of protection by preventing an attacker from installing a "rogue" JBoss ON agent and letting it register itself on the JBoss ON system, so that the rogue agent has access to the network. Although setting up authentication is more complicated than using encryption alone, it is worth the effort to implement for the additional protection, especially if there are vulnerabilities in the network setup.

3.1. Setting up Encryption

All that need to be done to set up encryption is to enable the SSL transport connectors in the JBoss ON server and agent configuration files. There are two transport options for SSL, sslservlet and sslsocket.
The JBoss ON server has a default certificate that it can use for encryption and the agent can generate a self-signed certificate, so it's not necessary to generate or install additional SSL certificates for encryption alone.
  1. First, enable SSL encryption on the JBoss ON server.
    1. Shut down the JBoss ON server. 
      serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh stop
    2. Open the serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.properties file for the JBoss ON server.
    3. Edit the rhq.communications.connector.* settings to use SSL. To use the sslsocket transport method, which is recommended for authentication, update the rhq.communications.connector.transport method, set the port number to use for the socket, and remove the servlet specified in the transport parameters setting. 
      rhq.communications.connector.transport=sslsocket   
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=55555   
rhq.communications.connector.transport-params=
      To use the sslservlet transport method, all that's necessary is to change the rhq.communications.connector.transport method. 
      rhq.communications.connector.transport=sslservlet   
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=
rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet
    4. For setting encryption alone, make sure that certificate-based authentication is disabled: 
      rhq.server.tomcat.security.client-auth-mode=false
rhq.server.client.security.server-auth-mode-enabled=false
    5. Optionally, define the secure protocol to use. The default is TLS (which is usually fine), but you can set it to SSL. 
      rhq.server.tomcat.security.secure-socket-protocol=TLS
rhq.server.client.security.secure-socket-protocol=TLS
    6. Save the changes, and restart the JBoss ON server. 
      serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh start
    7. Verify that the end point address and port number given in the configuration are actually the settings set for the server in JBoss ON.
      1. Click the Administration tab in the top menu.
      2. In the Topology box on the left, select the Servers item.
      3. Check the port number in the Secure Port column.
      4. If the value is wrong, click the name of the server to open the edit page.
      5. Click the Edit under the server information, and reset the end point address or port as necessary.
  2. Then, enable SSL encryption in the agent.

    Note

    This shows how to edit the agent configuration by editing the agent configuration file. The agent configuration can also be edited by going through the advanced setup mode in the agent start script: 
    agentRoot/rhq-agent/bin/rhq-agent.sh --cleanconfig --setup --advanced
    1. Open the agent configuration file: 
      vim agentRoot/rhq-agent/conf/agent-configuration.xml
    2. Change the transport protocol to sslsocket. 
      <entry key="rhq.communications.connector.transport"        value="sslsocket" />
    3. Set the server connection information so that it matches the configuration for the server. The bind address for the server is commented out by default, and the other parameters are set to the JBoss ON server defaults, including using sslservlet for the server's transport protocol. 
      <entry key="rhq.agent.server.transport"        value="sslsocket" />
<entry key="rhq.agent.server.bind-port"        value="55555" />
<entry key="rhq.agent.server.bind-address"     value="server.example.com" />
<entry key="rhq.agent.server.transport-params" value="" />
<entry key="rhq.communications.connector.transport" value="sslservlet" />
    4. For setting encryption alone, make sure that certificate-based authentication is disabled. These parameters can be left commented out or can be explicitly set to turn off authentication. 
      <entry key="rhq.communications.connector.security.client-auth-mode"       value="none" />
<entry key="rhq.agent.client.security.server-auth-mode-enabled" value="false" />
    5. Optionally, define additional protocol settings for the agent. This is necessary if the server is configured to use transport protocols other than TLS. 
      <entry key="rhq.communications.connector.security.secure-socket-protocol" value="TLS" />
<entry key="rhq.agent.client.security.secure-socket-protocol"   value="TLS" />
    6. Exit the agent and restart it, using the --cleanconfig option to load the new configuration. 
      agentRoot/rhq-agent/bin/rhq-agent.sh --cleanconfig

3.2. Setting up Client Authentication Between Servers and Agents

Authenticationis the process of verifying something's identity. With certificate-based authentication, an entity has to obtain a certificate file from a trusted source and, when initiating an SSL connection, that certificate is used to identify that entity. This ensures that the only parties involved in an SSL connection are who they say they are.
To set up certificate-based authentication for JBoss ON, several steps need to be taken. Encryption has to be enabled, certificates have to be issued and stored for the JBoss ON server and agents, and the servers and agents have to be configured to reject messages from untrusted clients.
SSL authentication for JBoss ON is bi-directional. The agents are configured to authenticate to the server, and then the server is configured to authentication to the agents.

Note

It is possible to configure one-way authentication, where only the server or only the agents have to authenticate. The best security is with bi-directional authentication, which is the configuration given here.
There are two transport methods in JBoss ON that allow SSL connections, sslservlet and sslsocket.
The procedure below uses sslsocket, which allows the default given port to be used for GUI connections while a special port is used for server-agent SSL connections.
Using sslservlet leverages the embedded Tomcat server, but this requires GUI users to authenticate to the server as well as enabling certificate-based authentication for agents. To allow GUI users to authenticate using their usernames and passwords, set up SSL more or less as outlined below (with some difference in the configuration file settings) and edit the JBoss ON server's Tomcat configuration file (serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/deploy/jboss-web.deployer/server.xml to uncomment the <Connector> section which says Provides a secure but un-authenticated https connector for browsers to use. and set the port for them to use.
  1. Enable encryption, as in Section 3.1, “Setting up Encryption”, only make sure that client authentication is not disabled.
  2. SSL socket connections will occur over a user-defined port. If necessary, open the firewall or VPN to allow access to that port.
  3. Generate SSL certificates for each JBoss ON server and agent. For example: 
    keytool -genkey -dname "CN=server1.example.com"  -keystore server1-keystore.dat -validity 3650 -alias server1 -keyalg DSA -storetype JKS -keypass secret -storepass secret
    This creates a self-signed certificate with the following characteristics:
    • A common name (CN) value that is the same as the server hostname, server1.example.com. The -dname value must be the same as the hostname because during the initial steps of the SSL connection (the SSL handshake), the client will verify that the same identity which was issued the certificate is the same as the one presenting it. Meaning, it will match the hostname in the CN against the hostname of the server or agent presenting the certificate.
    • A keystore file called server1-keystore.dat
    • A validity period of 3650 days
    • An alias of server1
    • A key algorithm of DSA
    • Stored in the JKS format in the keystore
    • Key and storage passwords of secret
    Your organization may have a method already for generating or obtaining certificates. This example uses keytool; other utilities, like certutil, can be used as well. The keytool documentation is available through the Oracle-Sun site at http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html.
  4. Put each self-signed certificate in a single truststore file.
    1. Export the self-signed certificate from each keystore: 
      keytool -export -keystore server1-keystore.dat -alias server1 -storetype JKS -storepass secret -file server1-cert
    2. Import every certificate into a single truststore file: 
      keytool -import -keystore truststore.dat -alias server1 -storetype JKS -file server1-cert -noprompt -keypass secret -storepass secret
      -alias is the name to give to the imported certificate in the truststore. For convenience, this is the same as the alias of the original keystore file.

      Important

      Import every exported server and agent certificate into the same truststore file.
    3. Verify that all the certificates were successfully imported by using the keytool to list the certificates: 
      keytool -list -keystore truststore.dat -storepass secret -storetype JKS
									
Keystore type: JKS
Keystore provider: SUN
									
Your keystore contains 2 entries
									
server2, Feb 25, 2011, trustedCertEntry,
Certificate fingerprint (MD5): 24:D9:8A:50:BA:1B:26:08:DC:44:A8:2A:9E:8A:43:D9
server, Feb 25, 2011, trustedCertEntry,
Certificate fingerprint (MD5): 91:F8:78:15:21:E8:0C:73:EC:B6:3B:1D:5A:EC:2B:01
  5. Distribute both the keystore and the truststore files to all the JBoss ON and server and agent machines. Be sure to distribute the keystores only to the machines which match the hostname in the CN of the certificate; putting the keystore on the wrong machine will cause SSL connections to fail.
    1. For the server, copy the keystore into the serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/conf/ directory of the JBoss AS server embedded in the JBoss Operations Network server. Make sure this file is named keystore.dat.
    2. For the server, copy the truststore into the serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/conf/ directory of the embedded JBoss AS server. Make sure this file is named truststore.dat.
    3. For the agent, copy the keystore into the agentRoot/rhq-agent/conf directory. Any certificate file in the agentRoot/rhq-agent/conf directory is retained even after an automatic update.
  6. Shut down the JBoss ON server. 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh stop
  7. Open the rhq-server.properties file for the JBoss ON server. 
    vim serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.properties
  8. Enable client authentication by setting the rhq.communications.connector.security.client-auth-mode parameter to need and the rhq.server.client.security.server-auth-mode-enabled parameter to true.
    Set the information about the keystore and truststore files.
    All of the configuration for incoming messages (agent-to-server communications) is set in rhq.communications.connector.security.* parameters. The configuration for outgoing messages is set in rhq.server.client.security.* parameters. 
    # Server-side SSL Security Configuration (for incoming messages from agents)
# These are used when secure transports other than sslservlet are used
rhq.communications.connector.security.secure-socket-protocol=TLS
rhq.communications.connector.security.keystore.file=${jboss.server.home.dir}/conf/keystore.dat
rhq.communications.connector.security.keystore.algorithm=SunX509
rhq.communications.connector.security.keystore.type=JKS
rhq.communications.connector.security.keystore.password=secret
rhq.communications.connector.security.keystore.key-password=secret
rhq.communications.connector.security.keystore.alias=server1
rhq.communications.connector.security.truststore.file=${jboss.server.home.dir}/conf/truststore.dat
rhq.communications.connector.security.truststore.algorithm=SunX509
rhq.communications.connector.security.truststore.type=JKS
rhq.communications.connector.security.truststore.password=secret
rhq.communications.connector.security.client-auth-mode=need

...

# Client-side SSL Security Configuration (for outgoing messages to agents)
rhq.server.client.security.secure-socket-protocol=TLS
rhq.server.client.security.keystore.file=${jboss.server.home.dir}/conf/keystore.dat
rhq.server.client.security.keystore.algorithm=SunX509
rhq.server.client.security.keystore.type=JKS
rhq.server.client.security.keystore.password=secret
rhq.server.client.security.keystore.key-password=secret
rhq.server.client.security.keystore.alias=myhost
rhq.server.client.security.truststore.file=${jboss.server.home.dir}/conf/truststore.dat
rhq.server.client.security.truststore.algorithm=SunX509
rhq.server.client.security.truststore.type=JKS
rhq.server.client.security.truststore.password=secret
rhq.server.client.security.server-auth-mode-enabled=true
  9. Save the file and restart the server. 
    serverRoot/jon-server-3.0.0.GA1/bin/rhq-server.sh start
  10. In the agent configuration file, uncomment the lines related to secure connections. These parameters begin with rhq.communications.connector.security.* and rhq.agent.client.security.* for agent-to-server communications and server-to-agent connections, respectively.
    Fill in the appropriate values. 
    <entry key="rhq.communications.connector.security.secure-socket-protocol" value="TLS" />
<entry key="rhq.communications.connector.security.keystore.file"          value="conf/keystore.dat" />
<entry key="rhq.communications.connector.security.keystore.algorithm"     value="SunX509" />
<entry key="rhq.communications.connector.security.keystore.type"          value="JKS" />
<entry key="rhq.communications.connector.security.keystore.password"      value="rhqpwd" />
<entry key="rhq.communications.connector.security.keystore.key-password"  value="rhqpwd" />
<entry key="rhq.communications.connector.security.keystore.alias"         value="rhq" />
<entry key="rhq.communications.connector.security.truststore.file"        value="conf/truststore.dat" />
<entry key="rhq.communications.connector.security.truststore.algorithm"   value="SunX509" />
<entry key="rhq.communications.connector.security.truststore.type"        value="JKS" />
<entry key="rhq.communications.connector.security.truststore.password"    value="" />
<entry key="rhq.communications.connector.security.client-auth-mode"       value="none" />

<entry key="rhq.agent.client.security.secure-socket-protocol"   value="TLS" />
<entry key="rhq.agent.client.security.keystore.file"            value="conf/keystore.dat" />
<entry key="rhq.agent.client.security.keystore.algorithm"       value="SunX509" />
<entry key="rhq.agent.client.security.keystore.type"            value="JKS" />
<entry key="rhq.agent.client.security.keystore.password"        value="rhqpwd" />
<entry key="rhq.agent.client.security.keystore.key-password"    value="rhqpwd" />
<entry key="rhq.agent.client.security.keystore.alias"           value="rhq" />
<entry key="rhq.agent.client.security.truststore.file"          value="conf/truststore.dat" />
<entry key="rhq.agent.client.security.truststore.algorithm"     value="SunX509" />
<entry key="rhq.agent.client.security.truststore.type"          value="JKS" />
<entry key="rhq.agent.client.security.truststore.password"      value="" />
<entry key="rhq.agent.client.security.server-auth-mode-enabled" value="false" />

    Note

    This shows how to edit the agent configuration by editing the agent configuration file. The agent configuration can also be edited by going through the advanced setup mode in the agent start script: 
    agentRoot/rhq-agent/bin/rhq-agent.sh --cleanconfig --setup --advanced

3.3. Troubleshooting SSL Problems

The most common symptom of an SSL connection problem is that the agent will hang when it starts up because it is unable to establish a connection to the JBoss ON server. There are several different areas to check when an SSL problem occurs.

3.3.1. Common SSL Connection Issues

An SSL problem is simply a connection problem, which indicates that there is a problem with the agent or server configuration. There are some general areas to check to make sure that the configuration is all right:
  • Make sure that both the agent and the server hostnames are resolvable to the hostnames in their server certificates.
  • Make sure that port number given for the server's secure port is actually the port number configured for the server. Check the Administration > High Availability > Servers page and verify that the public endpoint address and port are correct. Edit the server definition in the UI so they are the same as the SSL configuration.
    Server Hostname and Port Configuration

    Figure 1. Server Hostname and Port Configuration

    If these values do not match the same values configured for the SSL connection, the agent will not be able to talk to the server.
  • Make sure that both the agent and the server hostnames are resolvable to the hostnames in their server certificates.
  • Make sure that every certificate that is used for agent-server communication is stored in the requisite keystores with the proper aliases.
  • Check that the password is properly set to access the keystore.
  • Make sure that the communication is set to use TLS.
  • Validate the server and agent configuration, especially the assigned transport (socket or servlet) options. There are examples of configuration in Section 3.3.3, “Example SSL Configuration”.
  • If client authentication is required and the server is using the sslservlet transport option, make sure that every user who connects to the JBoss ON UI has an installed user certificate so that they can connect to the server UI using client authentication. As with the agent certificate, the user certificates must be stored in the server's keystore, Section 3.2, “Setting up Client Authentication Between Servers and Agents”.
    If users are unable to connect using client authentication, then change the server to use sslsocket instead of sslservlet.

3.3.2. Enabling SSL Debugging

Enabling verbose logging in the agent can return more details SSL communication messages in the agent log, which can help diagnose connection problems.
  1. Open the agent environment variable file. This defines some settings for the JVM which the agent runs in, including debug log settings. 
    vim agentRoot/rhq-agent/bin/rhq-agent-env.sh
  2. Add a RHQ_AGENT_ADDITIONAL_JAVA_OPTS line to set a debug environment variable. 
    RHQ_AGENT_ADDITIONAL_JAVA_OPTS="-Djavax.net.debug=all"
  3. Restart the agent. 
    agentRoot/rhq-agent/bin/rhq-agent.sh

3.3.3. Example SSL Configuration

These examples show what correct configuration looks like in both the server and the agent configuration files for the different encryption and authentication configuration scenarios.

Example 1. Encryption Only: Server (sslservlet) and Agent (sslsocket)

Server Configuration Agent Configuration 
rhq.communications.connector.transport=sslservlet
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=
rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet
rhq.server.tomcat.security.client-auth-mode=false
rhq.server.client.security.server-auth-mode-enabled=false
 
<entry key="rhq.agent.server.transport"        value="sslservlet" />
<entry key="rhq.agent.server.bind-port"        value="7443" />
The agent configuration defines the server's connection information, so it can be either sslservlet or sslsocket. The agent can only receive incoming messages over sslsocket.

Example 2. Encryption Only: Server (sslsocket) and Agent (sslsocket)

Server Configuration Agent Configuration 
rhq.communications.connector.transport=sslsocket
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=7800
rhq.communications.connector.transport-params=
rhq.server.tomcat.security.client-auth-mode=false
rhq.server.client.security.server-auth-mode-enabled=false
 
<entry key="rhq.agent.server.transport"        value="sslsocket" />
<entry key="rhq.agent.server.bind-port"        value="7800" />
<entry key="rhq.agent.server.transport-params" value="" />
Because the agent configuration defines the server's connection information, it must match the configuration in the server's rhq-server.properties file.

Example 3. Encryption and Client Authentication: Server (sslservlet) and Agent (sslsocket)

Server Configuration Agent Configuration 
rhq.communications.connector.transport=sslservlet
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=
rhq.communications.connector.transport-params=/jboss-remoting-servlet-invoker/ServerInvokerServlet
rhq.server.tomcat.security.client-auth-mode=true
rhq.server.client.security.server-auth-mode-enabled=true
 
<entry key="rhq.agent.server.transport"        value="sslservlet" />
       <entry key="rhq.agent.server.bind-port"        value="7443" />

Example 4. Encryption and Client Authentication: Server (sslsocket) and Agent (sslsocket)

Server Configuration Agent Configuration 
rhq.communications.connector.transport=sslsocket
rhq.communications.connector.bind-address=
rhq.communications.connector.bind-port=55555
rhq.communications.connector.transport-params=

rhq.communications.connector.security.client-auth-mode=true
rhq.server.client.security.server-auth-mode-enabled=true
 
<entry key="rhq.agent.server.transport"        value="sslsocket" />
<entry key="rhq.agent.server.bind-port"        value="55555" />
<entry key="rhq.agent.server.transport-params" value="" />
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.