[WFCORE-5120] Proposal for automatic registration of client side / JV…

…M wide default SSLContext

elytron/WFCORE-5120-client-default-ssl-context.adoc

@@ -0,0 +1,111 @@
+= WFCORE-5120 Automatic registration of client side / JVM wide default SSLContext
+:author:            Diana Vilkolak Krepinska
+:email:             dvilkola@redhat.com
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+
+This issue is about providing ability to register a client side JVM wide default https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/net/ssl/SSLContext.html[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 https://docs.oracle.com/javase/9/docs/api/java/security/Provider.html[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 https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/net/ssl/SSLContext.html#getDefault()[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
+
+* https://issues.redhat.com/browse/ELY-2112[ELY-2112]
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFCORE-4144[WFCORE-4144]
+* https://issues.redhat.com/browse/WFLY-13762[WFLY-13762]
+* https://issues.redhat.com/browse/WFCORE-5101[WFCORE-5101]
+* https://issues.redhat.com/browse/WFCORE-5120[WFCORE-5120]
+* https://issues.redhat.com/browse/WFLY-14846[WFLY-14846]
+
+=== Dev Contacts
+
+* mailto:dvilkola@redhat.com[Diana Vilkolak Krepinska]
+
+=== QE Contacts
+
+* mailto:fburzigo@redhat.com[Fabio Burzigotti]
+
+
+=== Testing By
+// Put an x in the relevant field to indicate if testing will be done by Engineering or QE.
+// Discuss with QE during the Kickoff state to decide this
+* [x] 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
+// Remove the x next to the relevant field if the feature in question is not relevant
+// to that kind of WildFly installation
+* [x] Traditional standalone server (unzipped or provisioned by Galleon)
+
+* [x] Managed domain
+
+* [x] OpenShift s2i
+
+* [x] Bootable jar
+
+== Requirements
+
+=== Hard Requirements
+
+* Implementation of new https://docs.oracle.com/javase/9/docs/api/java/security/Provider.html[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
+
+Automatic smoke tests - placed in `wildfly-elytron` repository. Most important use cases whould be covered. This includes :
+ * 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.
+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.
+
+Once the default SSL context is set for the JVM, it cannot be overwritten. So to not mess with other tests in the testsuite, each automatic test for this provider will run in its own JVM that is terminated after the test finishes. This slows the testsuite. Because of this, only smoke tests should be put in the testsuite and other testing can be done manually.
+
+== 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.