Client-Side HTTPS Support
Akka HTTP supports TLS encryption on the client-side as well as on the server-side.
The central vehicle for configuring encryption is the
HttpsContext, which can be created using
the static method
HttpsContext.create which is defined like this:
public static HttpsContext create(SSLContext sslContext, Option<Collection<String>> enabledCipherSuites, Option<Collection<String>> enabledProtocols, Option<ClientAuth> clientAuth, Option<SSLParameters> sslParameters)
In addition to the
cachedHostConnectionPool methods the
akka.http.javadsl.Http extension also defines
cachedHostConnectionPoolTls. These methods work identically to their counterparts without the
with the exception that all connections will always be encrypted.
superPool methods determine the encryption state via the scheme of the incoming request,
i.e. requests to an "https" URI will be encrypted, while requests to an "http" URI won't.
The encryption configuration for all HTTPS connections, i.e. the
HttpsContext is determined according to the
- If the optional
httpsContextmethod parameter is defined it contains the configuration to be used (and thus takes precedence over any potentially set default client-side
- If the optional
httpsContextmethod parameter is undefined (which is the default) the default client-side
HttpsContextis used, which can be set via the
- If no default client-side
HttpsContexthas been set via the
Httpextension the default system configuration is used.
Usually the process is, if the default system TLS configuration is not good enough for your application's needs,
that you configure a custom
HttpsContext instance and set it via
Afterwards you simply use
singleRequest without a specific
httpsContext argument, which causes encrypted connections
to rely on the configured default client-side
If no custom
HttpsContext is defined the default context uses Java's default TLS settings. Customizing the
HttpsContext can make the Https client less secure. Understand what you are doing!
Hostname verification proves that the Akka HTTP client is actually communicating with the server it intended to communicate with. Without this check a man-in-the-middle attack is possible. In the attack scenario, an alternative certificate would be presented which was issued for another host name. Checking the host name in the certificate against the host name the connection was opened against is therefore vital.
HttpsContext enables hostname verification. Akka HTTP relies on the Typesafe SSL-Config library
to implement this and security options for SSL/TLS. Hostname verification is provided by the JDK
and used by Akka HTTP since Java 7, and on Java 6 the verification is implemented by ssl-config manually.
We highly recommend updating your Java runtime to the latest available release, preferably JDK 8, as it includes this and many more security features related to TLS.