SSL Handling

SSL Handling

Introduction

The following document is about handling SSL in our components. Notice that this is a very complex issue. It is impossible to describe everything about using SSL in every situation possible. We will try to tell you the basics about using SSL in our ConnectPlaza application.

Note that ConnectPlaza generates Java applications for you. Do not confuse this with windows certificate handling or other SSL related things on other systems. Java handles SSL on its own terms. That said, how did we implement SSL usage in ConnectPlaza?

Java uses Java Key Stores as a way to keep track of its certificates used for SSL handshakes. ConnectPlaza has 2 default .jks files. You can find them in the following directory: <installation directory>/context with the following names:

  • connectplaza_keystore.jks
  • connectplaza_truststore.jks

If you have any knowledge about java, this will be somewhat familiar to you. If not, do not give up hope, rescue is near.

What is a Java Keystore

A Java Key Store is a repository of security certificates. These can be authorization certificates or key certificates (public certificate and corresponding private keys). Those can be used in SSL encryption. In ConnectPlaza we use both a keystore and a truststore, but both are Java Key Stores.

ConnectPlaza keystore

The ConnectPlaza keystore is the place where we store the keypairs for the connections to our services. The connecting party must have your public certificate to connect to your service. For instance if you have an HTTPS listener, you store the keypair (Private key and Public certificate) of the connecting server in the keystore. The Keystore also contains private keys used for Authentication when connecting to servers that require client SSL based authentication. Finally private keys can be used for Signing and Decrypting digital messages.

ConnectPlaza truststore

The ConnectPlaza truststore is the place where we store the public certificates of the sites we trust. These are sites your application connects to. It also contains root certificates so it is possible to automatically trust all certificates that are signed with this root certificate. Finally public keys can also be used for Signature Verification and Encryption of digital messages.

 

Protocol

The ConnectPlaza keystore and truststore accept keys and certificates in the X.509v3 standard. You can use the .pfx or .p12 files to upload the certificates in the java key store. This can be self-signed certificates, or keys obtained by a certificate reseller.

Using Java's own trusted CA SSL root certificates

As of version 3.x of ConnectAgent a default setting was introduced into the ConnectAgent Properties file to enable java's own trusted CA SSL root certificates.

CA stands for Certificate Authority. The CA is a global entity that provides root certification.

connect.ssl.ca.truststore=true

Open the file [connectplaza-agent-root]/conf/connectplaza-agent.properties. If you have an original pre-3.x version of the agent installed (installation of a 2.x version and updated to 3.x is also a pre 3.x original ConnectAgent), this setting is probably set to false.

If you set this setting to true, you can automatically connect to all SSL endpoints that contain certificates trusted by a common CA. Similar to how browsers automatically trust servers that are signed by a CA’s root certificate. You only need to add certificates to your ConnectPlaza Truststore in case of self-signed certificates and if, for any reason, a CA is not trusted by the Java Trusted CA SSL root certificates.

If this setting is set to false, you must explicitly trust all specific SSL servers you wish to connect to.

The default setting as of 3.x is therefore set to TRUE.

Key exchange algorithms (sFTP connections)

Using SSL you can run into certain key exchange issues. Some of the algorithms are no longer supported in your Java version, or the provider has another default installed. Changes in the security layer happen a lot these days. With the SFTP Key Exchange field, you can force the application to use a certain key exchange algorithm.

For more information about Key Exchange Algorithms, follow this link.

You can modify the used SSH Ciphers, MAC and key exhange by overriding the default settings using a Java System property: sftpKeyExchange. This system property can be set using the -DsftpKeyExchange=[yourciphers] in the ConnectPlaza Agent's wrapper.conf. You can add this property using the wrapper.conf's file format: i.e.:

wrapper.java.additional.X = -DsftpKeyExchange=[yourciphers]

And add this to the [connectplaza-agent-root]/yajsw/conf/wrapper.conf file.

Included protocols and cipher suits in your connectplaza-agent.properties file

As of version 3.4.0 there is a change in managing the cipher suits you may use when connecting with SSL. In the connectplaza-agent.properties file you will find two entries which looks like this:

#connect.jetty.sslconnector.included.protocols=TLSv1,TLSv1.1,TLSv1.2
#connect.jetty.sslconnector.included.ciphers=

This is the default setting. In some cases, it is needed to add one or more protocols. Normally you will add them here with their full names. It was, however, possible to use wild cards. .* was a possible option in version 3.3.2 and below. 

As of version 3.4.0 this is not allowed anymore. This setting will now be used for internal as well as external connections. Therefor you must put the full protocol name in this list. No wildcards allowed anymore.

When using protocols below TLSv1.2, you may get handshake errors if you do not add the needed ciphers to the connect.jetty.sslconnector.included.ciphers. Since TLS protocols older than 1.2 are considered unsafe, Java does not allow certain ciphers anymore by default. In order to support any older and unsafe ciphers, you can specify these in the included.ciphers property as shown above.

ATTENTION: Setting the entry connect.jetty.sslconnector.included.ciphers will affect the whole ConnectAgent. It is not an addition to the already existing ciphers. So use this with caution, because this will affect the security level of you entire Agent and therefor all the interfaces running on it.

In order to confirm any handshake errors are related to unsafe ciphers or to confirm that no common ciphers exist between server and client you may use the Java SSL Debug option to trace any problems concerning TLS/SSL

You can activate the SSL debug at the Agent’s boot by adding this setting to the Agent’s wrapper.conf

connectplaza.process.jvm.arg.ssldebug = -Djavax.net.debug=ALL

All relevant information pertaining the SSL handshake will be logged when this is enabled.

For more information about SSL tracing, check here.