Automatic registration of client side / JVM wide default SSLContext

In  elytron

Overview

This issue is about providing ability to register a client side JVM wide default SSLContext for the use of any libraries that support the use of the default SSL context.

This feature affects Elytron framework. More specifically, it affects default SSL context registration on the client side. Currently, it is possible to configure SSL contexts in Elytron’s client configuration and it is possible to configure specific SSL context that should be used for all outbound connections. End user can make use of this configured SSL context only by directly using Elytron client and its APIs.

This feature seeks to expose this default SSL context for users without having to interact with Elytron API directly in the code. This will be made possible by implementing a new java security provider . This java security provider will provide SSLContext with name "Default", which means that if this provider is registered with high enough priority, it will instantiate and return the configured SSLContext when end users call SSLContext.getDefault() in their code. This way client libraries can make use of it without modifying their code to use Elytron client. They must only register the provider in the JVM either statically by adding of this provider to java security file, or dynamically in the code by using standard java provider registration API.

Changes in code will be done only in Eytron repository.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Testing By

  • Engineering

  • QE

Affected Projects or Components

  • WildFly Elytron - security provider and tests will be added

  • WildFly - community documentation will be added

Other Interested Projects

NONE

Relevant Installation Types

  • Traditional standalone server (unzipped or provisioned by Galleon)

  • Managed domain

  • OpenShift s2i

  • Bootable jar

Requirements

Hard Requirements

  • Implementation of new java security provider that provides SSLContext under algorithm named "Default".

  • This provider will be able to load Elytron client configuration and will provide initialized SSL context for any client requesting it by using SSLContext.getDefault().

  • The provider will load the Elytron’s SSL context configuration either from the current authentication context obtained from classpath, or from authentication context generated by a file that is passed into the security provider (either programmatically to provider’s constructor or statically as an argument in a java.security file).

  • The SSL context configured to match ALL rules[1] is the one that will be initialized and returned by this provider.

[1] Elytron client can have multiple SSL contexts configured and rules are used to choose a single SSL context for the connection. Default SSL Context is the one that matches all rules.

Nice-to-Have Requirements

Non-Requirements

Implementation Plan

New java security provider that provides SSLContext named "Default" will be implemented. This provider will load Elytron client configuration and will return initialized SSL context for users that request it with method SSLContext.getDefault().

It will be possible to pass Elytron client’s configuration file path to the provider. If no path is specified, the provider will attempt to load the configuration from the current Elytron’s authentication context obtained from classpath - this can be either wildfly-config.xml file on classpath or the file specified by system property wildfly.config.url.

When this security provider is configured in JVM but there is no default SSL context configured in Elytron client, then this security provider will internally delegate the SSLContext instantiation to other providers. If no such other provider exists, NoSuchAlgorithmException exception will be thrown.

Test Plan

Once the default SSL context is set for the JVM, it is not overwritten by subsequent calls to SSLContext.getDefault(). So to not mess with other tests in the testsuite and have expected behaviour, each automatic test that uses SSLContext.getDefault() for this provider will run in its own JVM.

Automatic smoke tests - placed in wildfly-elytron repository. These include :

  • A test case that passes configuration file path to the provider. Make sure it can load the configuration successfully and the provider returned from SSLContext.getDefault() is the Elytron security provider.

  • A test case that generates a configuration from classpath. Make sure it can load the configuration successfully and the provider returned from SSLContext.getDefault() is the Elytron security provider.

  • Test that when this security provider is configured in JVM but there is no default SSL context configured in Elytron client, then this security provider will internally delegate the SSLContext instantiation to other provider.

Integration test in wildfly repository:

  • Set the priority of the elytron’s provider to be 1st in security providers and configure authentication context in Elytron client. Configure RESTEasy client’s SSLContext to be SSLContext.getDefault(). Test that the SSLContext that is configured in RESTEasy client is now from the Elytron provider. This test will be placed in manualmode tests in order to have separate JVM for this test case.

Manual tests - statically configure java.security file to have this provider placed with the highest priority. Try to connect to the server that requires custom SSL context configured and make sure such request is successful when the configuration is on classpath and does not succeed when it is not.

Community Documentation

Community documentation will be placed in WildFly repository under Elytron client section. The provider will be described under authentication-client element of client configuration, since that is where the SSL contexts can be configured.

Release Note Content

Elytron client now provides new java security provider that can be used to load default SSL context. When you register this provider in your JVM with high enough priority, then all client libraries that use SSLContext.getDefault() will obtain instance of the SSL context that is configured to be default in Elytron client configuration. This way you can make use of Elytron client’s SSL context configuration without interacting with Elytron API directly.