[WFLY-14984] Add support for encrypted expressions in the wildfly-con…

…fig.xml

elytron/WFLY-14984-encrypted-expression-for-client-config.adoc

@@ -0,0 +1,172 @@
+= Add support for encrypted expressions in the wildfly-config.xml
+:author:            Prarthona Paul
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+WildFly includes a common configuration framework that can be used to configure multiple clients, rather than relying on each client having their own configuration file. The configuration can be defined using a `wildfly-config.xml` file, where there are multiple configuration sections containing attributes whose values determine the configuration of the WildFly clients. 
+
+Attribute values for client configuration can include sensitive information. And while credential references can be used for some of them, others still need to be defined using plaintext. As a result, those attributes are still exposed and make the application vulnerable. Additionally, the password for the credential store needs to be defined as clear-text, which is not ideal. 
+
+This feature adds support for encrypted expressions for attributes in `wildfly-config.xml` file, which allows users to avoid specifying sensitive information using plaintext. Instead, encrypted expressions can be used to specify these information. A configuration section named `encrypted-expression` would be added, which would reference a `secret-key-credential-store` to extract encrypted expressions. It would also have a resolver, which would be backed by the secret-key-credential-store. The `secret-key-credential-store` can be created either using the `elytron-tool`.
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/WFLY-14984[WFLY-14984]
+
+// === Related Issues
+
+// * https://issues.redhat.com/browse/WFCORE[WFCORE-XXXX]
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+
+=== QE Contacts
+
+=== 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
+
+=== Other Interested Projects
+
+=== 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
+
+* The ability to specify attribute values as encrypted expressions should be added to wildfly-config.xml. 
+
+* The parsing needs to be able to run separately from the application server, as the server may not be running while the client configuration is being set up. 
+
+* Configurations may not depend on components created for server configuration, such as `resolvers` or `elytron/expression`. The resolver for the encrypted expression should be configured through the client configuration. 
+
+* The `encrypted-expression` would be a new configuration block added to the client config under the new schema. The new attributes added include `resolvers`, with attributes called `resolver` under it. Additionally, <credential-stores> attribute would be added to the schema with the <credential-store> attributes added to it. The structures of this attribute would be the same as the one one under the `authentication-client` schema. 
+
+** There may be multiple `resolver` attribute listed under <resolvers>, and there may be multiple <credential-store> attributes added under <credential-stores>.
+
+** The configuration for this block can be specified as follows: 
+```
+<encrypted-expression>
+	<credential-store name="credential-store-name" type="PKCS12" provider="provider-name"/>
+        <attributes>
+            <attribute name="path" value="path/to/credential-store-name.cs" />
+        </attributes>
+        <protection-parameter-credentials>
+            <clear-password password="password" />
+        </protection-parameter-credentials>
+    </credential-store>
+    <resolvers>
+        <resolver name= “resolver-name” credential-store= “credential-store-name key=“key”/>
+        <resolver name= “resolver-name-2” credential-store= “credential-store-name key=“example”/>
+    </resolvers>
+    <default-resolver name=resolver-name>
+</encrypted-expression>
+```
+Note that the initial password for the secret-key-credential-store used for the resolver would need to be specified in clear-text. 
+
+Once parsing is done, the resolver would need to be created programmatically (if not created by the server already) and be connected with the secret-key-credential-store. 
+
+* Once this has been configured, secret keys can be added to the credential store under different aliases and be used for client configuration as follows: 
+```
+<credential-store name="credential-store-name" type="PKCS12" provider="provider-name" >
+    <attributes>
+        <attribute name="path" value="path/to/credential-store-name.cs" />
+    </attributes>
+    <protection-parameter-credentials>
+	    <clear-password password={ENC::resolver-name:encrypted-expression} />
+    </protection-parameter-credentials>
+</credential-store>
+```
+
+* The encrypted expression would be created using the `--generate-secret-key` command and can be read using the `--export-secret-key` command. 
+
+=== Nice-to-Have Requirements
+
+* The parsing of the encrypted expression could be added as a separate namespace in the schema and should be added at the top of the xml file. 
+
+** While parsing the xml file, the section for encrypted expression and its resolver would need to be parsed before any other sections that reference it. 
+
+* Encrypted expressions can be added to different client configurations in addition to `authentication-client`. As a result, the parsing rules and sequences should be configured to be compatible with those schemas as well. 
+
+=== Non-Requirements
+
+* In the future, the ability to specify multiple encrypted expressions for one attribute or the ability to specify part of the value for an attribute may be added. 
+
+== Backwards Compatibility
+
+* Passwords and other sensitive information should still have the ability to be specified using clear-text or masked passwords for backwards compatibility. 
+
+* Credential stores may still be used to specify passwords for client config. 
+
+=== Default Configuration
+
+* If the configuration section for adding encrypted expression is not added, the passwords and other sensitive information can be specified using older methods, including clear-text, credential stores and masked passwords. 
+
+=== Importing Existing Configuration
+
+=== Deployments
+
+=== Interoperability
+
+//== Implementation Plan
+////
+Delete if not needed. The intent is if you have a complex feature which can 
+not be delivered all in one go to suggest the strategy. If your feature falls 
+into this category, please mention the Release Coordinators on the pull 
+request so they are aware.
+////
+
+== Security Considerations
+
+////
+Identification if any security implications that may need to be considered with this feature
+or a confirmation that there are no security implications to consider.
+////
+The elytron client would be configurable using the new support for encrypted expression, which would make clients more secure. 
+
+== Test Plan
+
+* Parsing for the xml file would be tested for the WildFly client. 
+* Parsing tests would also be added to the elytron client test suite. 
+* Tests would be added to the elytron test suite for testing elytron clients for expected functionalities. 
+* Tests may be added to other projects to test for expected behavior. 
+** Alternatively, integration tests would be added to the WildFly test suite for other projects as well.
+* Components of WildFly and the Elytron projects would be tested for functionality using integrated tests in the WildFly test suite. 
+
+== Community Documentation
+////
+Generally a feature should have documentation as part of the PR to wildfly master, or as a follow up PR if the feature is in wildfly-core. In some cases though the documentation belongs more in a component, or does not need any documentation. Indicate which of these will happen.
+////
+Documents for the new support for encrypted expression would be added to https://docs.wildfly.org/30/Client_Guide.html[WildFly Client Configuration].
+
+== Release Note Content
+////
+Draft verbiage for up to a few sentences on the feature for inclusion in the
+Release Note blog article for the release that first includes this feature. 
+Example article: http://wildfly.org/news/2018/08/30/WildFly14-Final-Released/.
+This content will be edited, so there is no need to make it perfect or discuss
+what release it appears in.  "See Overview" is acceptable if the overview is
+suitable. For simple features best covered as an item in a bullet-point list 
+of features containing a few words on each, use "Bullet point: <The few words>" 
+////