Update Security Hardening Doc

[Zech-Hein]

Please describe the problem you are having with the documentation. Is information missing, inaccurate, or unclear? Tell us about the context where you encountered the problem so we can understand how to address it.

doc page:

1. https://openliberty.io/docs/latest/server-configuration-hardening.html#password-encryption

   • Update Currently, Open Liberty supports AES-128 encryption
     to be Currently, Open Liberty supports AES-128 and AES-256 encryption
   • Update With AES encryption, the default encryption key that is used for decryption can be overridden by setting the wlp.password.encryption.key property. This property must not be set in the server.xml file, but in a separate configuration file that is included by the server.xml file. This separate configuration file must contain only a single property declaration, and must be stored outside the normal configuration directory for the server.
     to be
     With AES encryption, an encryption key must configured for decryption. The encryption key can be configured by setting either the wlp.password.encryption.key or wlp.aes.encryption.key variable. This variable must not be set in the server.xml file, but in a separate configuration file that is included by the server.xml file. This separate configuration file must contain only a single property declaration, and must be stored outside the liberty installation directory. For more information on setting wlp.aes.encryption.key, see [Bring your own AES-256 key for Liberty passwords](https://openliberty.io/docs/latest/bring-your-own-aes-256-key.html).
   • Remove the Use a pre-generated AES-256 key section from the page.

2. https://openliberty.io/docs/latest/reference/command/securityUtility-encode.html#_usage_examples

   • Update the usage example: securityUtility encode --encoding=aes
     to be securityUtility encode --encoding=aes --key=<encryption_key_string>
   • Update the description for that usage example
     from Encrypt a password with Advanced Encryption Standard (AES) encryption.
     to be Encrypt a password with Advanced Encryption Standard (AES) encryption by specifying an encryption key string.

3. https://openliberty.io/docs/latest/password-encryption.html

   • Update In Open Liberty, you can override the default key that is used for encrypting and decrypting by setting the wlp.password.encryption.key property
     to be In Open Liberty, you can configure the encryption key that is used for encrypting and decrypting by setting either the wlp.password.encryption.key property or wlp.aes.encryption.key property
   • Update For a more secure configuration, set the wlp.password.encryption.key property in a separate file that is stored outside the normal configuration directory for the server
     to be For a more secure configuration, set the encryption key property in a separate file that is stored outside the liberty installation directory
   • Update the example to have <variable name="wlp.aes.encryption.key" value="<your_aes_key>" /> or <variable name="wlp.password.encryption.key" value="yourKey" /> and add a note to say wlp.aes.encryption.key and wlp.password.encryption.key cannot be used at the same time.

[una-tapa]

Once this document review is finalized, please open a CIS benchmark defect with the corresponding hardening suggestions as we discussed in the meeting. FYI: looping in @NottyCode @clarkek123

[daveywebster]

Hi, some comments which I am not sure are applicable or not, but I thought I should bring them up ...

== 1 ==

In point number 1, there is the text in the "to be" which states: "...setting either the wlp.password.encryption.key or wlp.aes.encryption.key variable. This variable must not be set in the server.xml file, but in a separate configuration file..."

Therefore, in https://openliberty.io/docs/latest/server-configuration-hardening.html#password-encryption, doesn't the text above the example (showing the setting of the variable in server.xml) have to be updated?

i.e. The text "You can define the generated key directly in server.xml or in an included configuration file." (emphasis mine) needs to be changed? Especially as the example includes the property : name="wlp.aes.encryption.key" which is explicitly called out in the "to be" as not settable from server.xml?

== 2 ==

In point number 1, you call the server XML configuration elements "variables" in the "to be", but in other places, they are called "properties"?

i.e. "... The encryption key can be configured by setting either the wlp.password.encryption.key or wlp.aes.encryption.key variable. ..."

A minor consistency point.

[Zech-Hein]

Thank you for the input, David!

1. Your point is valid, which is why we are removing that example.

Remove the Use a pre-generated AES-256 key section from the page.

2. Also a valid point, we should be consistent, the examples define a config variable, but it may be more proper to call it a property as it can also be set in bootstrap.properties. I'll defer to @jantley-ibm

[jantley-ibm]

Re: 2, my thought was to say "property" when referring directly to the property itself, 'wlp.aes.encryption.key'; but then to say "variable" when referring to the setting of the property to some value (like so: <variable name="wlp.aes.encryption.key" value="<your_aes_key>" />).

I have made changes to the source, will provide a link or two shortly for review.

[jantley-ibm]

@Zech-Hein @daveywebster available for review:

1. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/server-configuration-hardening.html#password-encryption
2. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-encode.html#_usage_examples
3. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/password-encryption.html

[daveywebster]

Okay, looks good. My one query might be in the first link for password encryption , maybe you could put an example in there with a clear message like was shown in encryption key protection , but that's just my humble 2 pence. Cheers.

[jantley-ibm]

@daveywebster Could you provide an acceptable example? I'd be happy to add it to that section.

[daveywebster]

@daveywebster Could you provide an acceptable example? I'd be happy to add it to that section.

Hi, yes, could you use the same example from the first link for password encryption ? It's a different section, but really outlining the same (specific) information so the same example would be clear and I don't think this is redundant at all as it's useful info.

[Zech-Hein]

I agree with @daveywebster. The other changes look good to me 👍