• Introduction
• Cipher Suite Format
• Default Ciphers and Protocols
• Overriding Server defaults
• Overriding Client defaults

This feature was added in version 6.1 of Iguana.

Introduction

The default SSL security in Iguana has been upgraded to provide greater security. This protects against known protocol exploits, by preventing the use of insecure SSL protocols and ciphers. Future security is also addressed as the list of allowed protocols and ciphers can be updated (to allow for future threats).

The default settings were chosen with optimal security in mind, while still allowing for some backwards compatibility for older systems and browsers. If you need to connect to legacy systems that do not support the default SSL settings, then you can override the defaults see overriding the defaults below for details.

This upgrade applies to Server and Client security:

1. Server configuration:
   • Iguana’s web server
   • HTTPS components
2. Client APIs:
   • net.http
   • net.ftp
   • net.ftps

Cipher Suite Format [top]

Since Iguana implements SSL using the OpenSSL library, cipher suite lists are consumed in standard OpenSSL format. More information about OpenSSL cipher suites and their format can be read about here: https://www.openssl.org/docs/man1.0.2/apps/ciphers.html.

Default Ciphers and Protocols [top]

This section explains our SSL defaults and why we chose them.

Chosen ciphers and protocols

The following JSON object lists the default ciphers and versions that Iguana uses.

{
“ssl_versions“: “TLSv1.2 TLSv1.3”,
“ssl_cipher_suites“: “TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256”,
“ssl_ciphers“: “ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:!3DES:!RC4:!MD5:!DSS”
}

Reasons for the default security choices

SSL Versions

To prevent exploits like POODLE and BEAST attacks, the lowest default SSL version supported is TLS v1.1 for both client and server configurations. SSL v3 is vulnerable to POODLE, while TLS v1.0 is vulnerable to BEAST.

To use a version lower than TLS v1.1 you would need to override the default settings.

Ciphers

Ciphers are prioritized in the order they are provided in the cipher list. For this reason ChaCha20 is preferred as the fastest and safest in-software cipher, followed by AES128. To allow limited compatibility with older systems, we do not assume support for AESNI and thus do not prioritize AES256 above 128 and ChaCha20.

Insecure cipher suites have been disabled. This includes 3DES, as proven by the Sweet32 vulnerability, as well as RC4 due to numerous exploits.

To improve security, elliptical curve cipher suites (ECDHE) that allow for perfect forward secrecy are now fully supported. Many explanations exist online as to what perfect forward secrecy entails, but a high level explanation is that it will prevent any (previously) intercepted SSL communication from being deciphered in the future if the server’s SSL private key is later compromised. This is done by creating a temporary key for each SSL session instead of using the server’s private key. This means that if the server’s private key is compromised it cannot be used to decrypt any previously intercepted communication.

Overriding Server defaults [top]

Follow this process to override Server default ciphers and versions.

Server configurations apply to HTTPS when it is enabled for Iguana’s main web server (in Web Server Settings), and/or for Iguana’s HTTP channel components (in HTTP(S) Channels settings).

The following environment variable must be defined:

IFW_SSL_OVERRIDE_DEFAULT_OPTIONS=<any value>

This variable can be set to any value, as long as it is present on the system. To disable the override the variable must be deleted (the variable is not treated as a boolean so setting to 0 will not turn off the override).

In conjunction with this, a JSON file named ifw_ssl.conf must be placed in the current working directory. The file format is shown below (it is the same as that shown in chosen ciphers and protocols above). On startup, Iguana loads ifw_ssl.conf and uses the override options provided to initialize the SSL contexts for both server configurations.

If the file format is not correct, because the JSON cannot be parsed properly, or the cipher list/ssl version strings aren’t in the right format, an error will be thrown and Iguana will halt startup. (You will see an error message in the ServiceErrorLog.txt in the working directory). Iguana automatically skips any cipher suite strings it does not recognize. As long as there is at least one valid suite provided no error will be thrown.

The following example ifw_ssl.conf shows how to support the (old and insecure) SSLv3/TLSv1.0 protocols. This option would be used only if it was required that the Iguana server be available to clients running Windows XP SP2 on Internet Explorer or similar extremely outdated setups.

{
“ssl_versions“: “SSLv3 TLSv1 TLSv1.1 TLSv1.2 TLSv1.3”,
“ssl_cipher_suites“: “TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256”,
“ssl_ciphers“: “ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:!3DES:!RC4:!MD5:!DSS”
}

Overriding Client defaults [top]

Follow this process to override Client default ciphers and versions.

Client configurations Apply to SSL when it is enabled for the net.http, net.ftp and net.ftps APIs in the translator.

If you refer to the API help, you will see a new addition of ssl_ciphers in the list of available parameters for net.ftp.* and net.ftps.*. The same parameter has been added to net.http.* as well but as a new member of the ssl table parameter.

In similar fashion to our server overrides, you can utilize the ssl_ciphers parameter to override Iguana’s default SSL cipher suites. By supplying a new cipher suite list string (in the same OpenSSL format as shown for the server settings), Iguana will override it’s default cipher suites and use the ones provided.

To override the default allowed SSL versions, an ssl_version parameter can be supplied. This has existed in previous versions but the defaults have now been restricted to only allow TLSv1.1 and TLSv1.2 as was done for the server.

To override and allow TLSv1.0 as well, the tls-v1 value must supplied. When using this Iguana will attempt to connect to the target server using TLS1.2 first, and if is unsupported will try again with TLSv1.1 then TLSv1.0 until a supported version is agreed upon by both the client and server.

If an ssl-v3 parameter is supplied, then Iguana will attempt to use SSLv3 (after TLS fails). Due to the numerous exploits and security concerns SSLv3 it should only be used when all other options have been exhausted.