SSL settings
Per default the controller GUI is accessible via HTTP and SSL is disabled. It is highly recommended to secure your controller instance by enabling SSL.
Before enabling SSL you will need a valid SSL certificate for your controller domain. You can either use a self-signed certificate or obtain it from a certificate authority (CA).
In both cases you’ll get following files:
- the private key file (.key)
- the certificate file (.cert)
The controller requires the certificate in a Java KeyStore in JKS format. To generate the JKS KeyStore based on your .key and .cert files, follow the steps described here
As soon as you have your certificate in JKS format as a .jks file you can enable SSL as follow:
Put the keystore file (mydomain.jks for example) in conf folder of the controller and add the following lines to the step.properties file :
#-----------------------------------------------------
# SSL configuration
#-----------------------------------------------------
ui.ssl.enabled=true
ui.ssl.keystore.path=../conf/mydomain.jks
ui.ssl.keystore.password=<PASSWORD_DEFINED_DURING_P12_KEYSTORE_CREATION>
ui.ssl.keymanager.password=<PASSWORD_DEFINED_DURING_P12_KEYSTORE_CREATION>
#-----------------------------------------------------
HTTP Strict Transport Security (HSTS)
If you wish to use HTTP Strict Transport Security, you can additionally define the following properties.
Here, the (implicit) defaults are shown. You must at least set the ui.ssl.hsts.maxAge setting to a non-negative value for the header to be enabled. Note that it will usually not make sense to enable the includeSubdomains flag, but the option is available.
ui.ssl.hsts.maxAge=-1
ui.ssl.hsts.includeSubdomains=false
Controlling SSL Protocols and Cipher Suites
If you need fine-grained control over SSL protocols and cipher suites, for example for hardening your configuration, you can specify protocol and cipher suite exclusion/inclusion rules.
Examining the active configuration
By setting the configuration property ui.ssl.logProtocolsAndCipherSuites=true, the controller will log additional information on startup.
Here is an example with no further configuration applied (in other words, the defaults at the time of writing):
[main] INFO s.framework.server.ControllerServer - Logging SSL protocol and cipher suite information because ui.ssl.logProtocolsAndCipherSuites is enabled:
[main] INFO s.framework.server.ControllerServer - Include protocols:
[main] INFO s.framework.server.ControllerServer - Exclude protocols: SSL SSLv2 SSLv2Hello SSLv3
[main] INFO s.framework.server.ControllerServer - Include cipher suites:
[main] INFO s.framework.server.ControllerServer - Exclude cipher suites: ^.*_(MD5|SHA|SHA1)$ ^TLS_RSA_.*$ ^SSL_.*$ ^.*_NULL_.*$ ^.*_anon_.*$
Modifying the configuration
You can specify inclusion/exclusion rules using the configuration keys ui.ssl.includeProtocols, ui.ssl.excludeProtocols, ui.ssl.includeCipherSuites, and ui.ssl.excludeCipherSuites.
Each of these settings accepts a space-separated list of regular expressions which is split into a list, then passed on to the underlying implementation.
For related information, see for example the Jetty documentation.
Determining all supported protocols and cipher suites Unfortunately, there seems to be no easy way to get a list of all supported protocols/cipher suites. However, there is a workaround which involves temporarily setting the inclusion configurations to (only) invalid values, for instance:
ui.ssl.includeProtocols=invalid
ui.ssl.includeCipherSuites=invalid
When the controller is started with such a configuration, SSL will not be working correctly, but the implementation will complain about invalid settings, including the list of all supported values:
[main] INFO o.e.jetty.util.ssl.SslContextFactory - No Cipher Suite matching 'invalid' is supported
[main] WARN o.e.jetty.util.ssl.SslContextFactory - No supported Cipher Suite from [TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, ...]
[main] INFO o.e.jetty.util.ssl.SslContextFactory - No Protocols matching 'invalid' is supported
[main] WARN o.e.jetty.util.ssl.SslContextFactory - No selected Protocols from [TLSv1.3, TLSv1.2, TLSv1.1, TLSv1, SSLv3, SSLv2Hello]