WildFly Elytron

WildFly Elytron

TLS 1.3 support for WildFly with OpenSSL

WildFly 21 adds the ability to use TLS 1.3 with WildFly when using the OpenSSL TLS provider. This blog post will give an introduction to this new feature.

Disabled by Default

The use of TLS 1.3 is currently disabled by default when using the OpenSSL TLS provider. This is because if JDK 11 is in use and if there is a very large number of TLS 1.3 requests coming in, it is possible that a drop in performance (i.e., throughput and response time) will occur compared to when using TLS 1.2 with the OpenSSL TLS provider. It is recommended to test for performance degradation prior to enabling TLS 1.3 in a production environment.

Enabling TLS 1.3 on the Server Side

TLS 1.3 can be enabled by configuring the cipher-suite-names attribute in the SSL Context resource definition in the Elytron subsystem. Let’s take a look at a complete example.

Pre-requisite Configuration

As a first step, we’re going to enable one-way SSL for applications deployed to WildFly using the security enable-ssl-http-server CLI command:

Enabling one-way SSL

security enable-ssl-http-server --interactive
Please provide required pieces of information to enable SSL:

Certificate info:
Key-store file name (default default-server.keystore): server.keystore
Password (blank generated): secret
What is your first and last name? [Unknown]: localhost
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?y
Validity (in days, blank default): 30
Alias (blank generated): localhost
Enable SSL Mutual Authentication y/n (blank n):n

SSL options:
key store file: server.keystore
distinguished name: CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown,
C=Unknown
password: secret
validity: 30
alias: localhost
Server keystore file server.keystore, certificate file server.pem and server.csr
 file will be generated in server configuration directory.

Do you confirm y/n :y
Server reloaded.
SSL enabled for default-server
ssl-context is ssl-context-b0110cb7-595b-4de9-942b-e616690bb350
key-manager is key-manager-b0110cb7-595b-4de9-942b-e616690bb350
key-store   is key-store-b0110cb7-595b-4de9-942b-e616690bb350

As we can see from the output, the above command automatically generated a self-signed server certificate, added it to a newly created keystore, and added a new ssl-context resource, ssl-context-b0110cb7-595b-4de9-942b-e616690bb350, to the Elytron subsystem in order to enable one-way SSL for applications deployed to WildFly.

Configuring WildFly to use the OpenSSL TLS provider

There are two ways to configure WildFly to make use of the OpenSSL TLS provider.

Using the OpenSSL TLS provider by default

To configure the Elytron subsystem so that the OpenSSL TLS provider is used by default, the following commands can be used:

/subsystem=elytron:write-attribute(name=initial-providers, value=combined-providers)
/subsystem=elytron:undefine-attribute(name=final-providers)
reload
Configuring an SSL context to use the OpenSSL TLS provider

Instead of configuring the Elytron subsystem to use the OpenSSL TLS provider by default, it is also possible to specify that the OpenSSL TLS provider should be used for a specific SSL context by configuring the providers attribute for a server-ssl-context. Let’s update our server-ssl-context to specify that we want to use the OpenSSL TLS provider:

/subsystem=elytron/server-ssl-context=ssl-context-b0110cb7-595b-4de9-942b-e616690bb350:write-attribute(name=providers,value=openssl)
reload

Now, let’s try to access the WildFly landing page using curl:

curl -v -k https://localhost:8443
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=Unknown; ST=Unknown; L=Unknown; O=Unknown; OU=Unknown; CN=localhost
*  start date: Oct  6 14:58:16 2020 GMT
*  expire date: Nov  5 15:58:16 2020 GMT
*  issuer: C=Unknown; ST=Unknown; L=Unknown; O=Unknown; OU=Unknown; CN=localhost
*  SSL certificate verify result: self signed certificate (18), continuing anyway.

Since the security enable-ssl-http-server command simply generated a self-signed server certificate for testing purposes, this server certificate won’t be trusted by curl. This is why we specified the -k option in the curl command.

Notice that in the above output, we can see that the TLS 1.2 protocol was used for the connection and that the ECDHE-RSA-AES256-GCM-SHA384 cipher suite was used.

Switching to TLS 1.3

To enable TLS 1.3, we just need to update our ssl-context configuration in the Elytron subsystem to specify the cipher-suite-names attribute. The format of this attribute is colon separated list of the TLS 1.3 cipher suites that you would like to enable. We’re going to set this attribute to TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:

# This is only needed when the ssl-context is configured to use specific protocol version(s) other
# than TLS 1.3. In general, this is not needed when the protocols attribute is simply undefined.
/subsystem=elytron/server-ssl-context=ssl-context-b0110cb7-595b-4de9-942b-e616690bb350:write-attribute(name=protocols,value=[TLSv1.3])

/subsystem=elytron/server-ssl-context=ssl-context-b0110cb7-595b-4de9-942b-e616690bb350:write-attribute(name=cipher-suite-names,value=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256)
reload

Now, let’s try to access the WildFly landing page using curl again:

* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=Unknown; ST=Unknown; L=Unknown; O=Unknown; OU=Unknown; CN=localhost
*  start date: Oct  6 14:58:16 2020 GMT
*  expire date: Nov  5 15:58:16 2020 GMT
*  issuer: C=Unknown; ST=Unknown; L=Unknown; O=Unknown; OU=Unknown; CN=localhost
*  SSL certificate verify result: self signed certificate (18), continuing anyway.

Notice that this time, we can see that the TLS 1.3 protocol was used for the connection and that the TLS 1.3 TLS_AES_256_GCM_SHA384 cipher suite was used.

Summary

This blog post has given an overview on how TLS 1.3 can be used with WildFly with the OpenSSL TLS provider. For more details, take a look at the documentation.