SSL Handling
Introduction
The following document is about handling SSL in our components. Note that this is a complex subject. While it is impossible to explain everything related to SSL, we will attempt to outline the basics of SSL applicable to the ConnectPlaza environment
The ConnectAgent runs on the Java Runtime Environment. Consequently, it will not be affected by Windows certificate handling or other SSL related management tools on other types of systems.
Java handles SSL on its own terms. That said, how did we implement SSL usage in ConnectPlaza?
Java uses Java keystores 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
In the following sections, we will explain how these keystores and the certificates in them are used and how to manage them.
What is a Java keystore
A Java keystore is a repository of security certificates. These can be authorization certificates or key certificates (public certificates 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 keystores.
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 keystore. 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=trueOpen 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.
SFTP Crypto Algorithms
Using SSH you can run into certain crypto issues. Since ConnectPlaza 4.4.0, certain ciphers such as (3)DES and hashing algorithms such as SHA1 are no longer supported, due to their insecure nature. If certain connections to (older) SFTP servers require the use of these deprecated algorithms, you may need to override these settings.
For more information about SSH Security and its options, follow this link
You can modify the used SSH Ciphers, Server Host Key and Key Exchange settings by overriding the default settings using properties in the connectplaza-jvm-process.properties file. This file can be edited manually. Please refer to your server’s supported list of ciphers and algorithms.
Please note: these adjustments are Agent wide and will affect all (!) SFTP based connections.
SSH Server Host Key:
connectplaza.process.jvm.arg.jsch.server_host_key = -Djsch.server_host_key=[your algoritms]
SSH Server Key Exchange:
connectplaza.process.jvm.arg.jsch.kex = -Djsch.kex=[your algoritms]
SSH Server Ciphers:
connectplaza.process.jvm.arg.jsch.cipher = -Djsch.cipher=[your ciphers]
Please see this page for all options and their settings.
To find the correct settings, you have to check your log files. The JSCH Client throws an exception with some important information, like:
- jsch-proposal --> The algorithms or ciphers supported by JSCH
- server-proposal --> The algorithms or ciphers offered by the server
This will give you the answers to the missing algorithm or cipher.
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. Therefore 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 your entire Agent and therefore 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. Add the line below to the connectplaza-jvm-process.properties file.
connectplaza.process.jvm.arg.ssldebug = -Djavax.net.debug=ALLAll relevant information pertaining the SSL handshake will be logged when this is enabled.
For more information about SSL tracing, check here.