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..403bba77 --- /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 `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 <expression-resolvers>, with elements called <expression-resolver> under it. Additionally, <credential-stores> attribute would be added to the schema with the <credential-store> 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 <expression-resolvers>, and there may be multiple <credential-store> elements added under <credential-stores>. + +** The configuration for this block can be specified as follows: +``` +<encrypted-expression> + <credential-stores> + <credential-store name="my-credential-store" type="PropertiesCredentialStore"> + <attributes> + <attribute name="location" value="${credstore-path.env}"/> + </attributes> + <protection-parameter-credentials> + <clear-password password="password"/> + </protection-parameter-credentials> + </credential-store> + </credential-stores> + <expression-resolvers> + <expression-resolver name= “expression-resolver-name” credential-store= “credential-store-name" alias=“key”/> + <expression-resolver name= “expression-resolver-name-2” credential-store= “credential-store-name" alias=“example”/> + </expression-resolvers> + <default-expression-resolver name=expression-resolver-name> +</encrypted-expression> +``` +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 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="JCEKS" provider="provider-name" > + <attributes> + <attribute name="location" value="path/to/credential-store-name.cs" /> + </attributes> + <protection-parameter-credentials> + <clear-password password={ENC::expression-resolver-name:encrypted-expression} /> + </protection-parameter-credentials> +</credential-store> +``` + +* 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 <encrypted-expression> 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: <The few words>" +//// \ No newline at end of file