diff --git a/elytron/WFLY-14984-encrypted-expression-for-client-config.adoc b/elytron/WFLY-14984-encrypted-expression-for-client-config.adoc new file mode 100644 index 00000000..539e8972 --- /dev/null +++ b/elytron/WFLY-14984-encrypted-expression-for-client-config.adoc @@ -0,0 +1,186 @@ += Add support for encrypted expressions in the wildfly-config.xml +:author: Prarthona Paul +:email: prpaul@redhat.com +: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 elements 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 elements 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 elements 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 convert plaintext to encrypted expressions and vice versa. The secret-key-credential-store would be indicated by the `credential-store` tag with the `type` being `PropertiesCredentialStore`. It would also have a expression-resolver, which would be backed by one of the secret key aliases from the the secret-key-credential-store. The `secret-key-credential-store` can be created using the wildfly-elytron tool using the `credential-store` command and the `--create` option. + +== Issue Metadata + +=== Issue + +* https://issues.redhat.com/browse/WFLY-14984[WFLY-14984] + +=== Related Issues + +* https://issues.redhat.com/browse/ELY-2711[ELY-2711] + +=== 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. + +* Parsing for client configuration needs to be separate from parsing server configuration. + +* Configurations may not depend on components created for server configuration, such as `expression-resolvers` or `elytron/expression`. The expression-resolver for the encrypted expression on the client side 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 elements added include , with elements called under it. Additionally, attribute would be added to the schema with the elements 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 `expression-resolver` attribute listed under , and there may be multiple elements added under . + +** The configuration for this block can be specified as follows: +``` + + + + + + + + + + + + + + + + + +``` +Note that the initial password for the credential-store used for the expression-resolver would need to be specified in clear-text if it is a keystoreCredentialStore. However, if it is of PropertiesCredentialStore type, then the password would no longer need to be specified. + +Once parsing is done, the expression-resolver would need to be created programmatically and be connected with the associated secret-key alias from a 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: +``` + + + + + + + + +``` + +* The secret keys that would be used to encrypt expressions would be created using the `--generate-secret-key` command and can be read using the `--export-secret-key` command as follows: +``` +$ bin/elytron-tool.sh credential-store --generate-secret-key example --location=standalone/configuration/mycredstore.cs +``` +* In order to encrypt a clear-text expression, `--encrypt` option in the wildfly-elytron tool can be used as follows: +``` +$ bin/elytron-tool.sh credential-store --location standalone/configuration/store-one.cs --type PropertiesCredentialStore --encrypt key +Clear text value: +Confirm clear text value: +Clear text encrypted to token 'RUxZAUMQvGzk6Vaadp2cahhZ6rlPhHOZcWyjXALlAthrENvRTvQ=' using alias 'key'. +``` + +* expression-resolvers can also be backed by a `credential-store`, which is a KeyStoreCredentialStore. However, when using a KeyStoreCredentialStore type credential store, the protection parameter, which is the password needs to be specified in clear-text inside the tag. + +=== 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 expression-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: " +//// \ No newline at end of file