Better usage explanation is needed for securityUtility

[una-tapa]

Describe the bug

securityUtility needs better usage description.

Steps to Reproduce

While @KyleAure was debugging Issue 28082, he found the following issue.

Test password: passwordWith$InIt
I got different results from the securityUtility tool and PasswordUtil.encode
securityUtility: {xor}Lz4sLCgwLTsINis3
PasswordUtility: {xor}Lz4sLCgwLTsINis3exYxFis=
If I try to PasswordUtil.decode both of these I get
securityUtility: passwordWith
PasswordUtility: passwordWith$InIt

Since the securityUtility gets the password passed in, we needed to add escape (\) in front of ($) character.

$ ./securityUtility encode passwordWith\$InIt
{xor}Lz4sLCgwLTsINis3exYxFis=

Expected behavior

The usage description should include the need to escape special characters.
Need some investigation and the list of characters if possible.

Usage: securityUtility {encode|createSSLCertificate|createLTPAKeys|tlsProfiler|help} [options]

Actions:

    encode
	Encode the provided text.
    The following characters must be escaped for proper encoding [$, ...]
    For example pa$$W0rd should be provided as pa\$\$W0rd

...

**Diagnostic information:**  
 - OpenLiberty Version: [e.g. 21.0.0.8 - 21.0.0.10]
 - Affected feature(s) [e.g. mpHealth-3.0]
 - Java Version: [i.e. full output of `java -version`]
 - server.xml configuration (WITHOUT sensitive information like passwords)
 - If it would be useful, upload the messages.log file found in `$WLP_OUTPUT_DIR/messages.log`

**Additional context**  
Add any other context about the problem here.

[KyleAure]

Thanks for opening this! I'm not sure which characters need to be escaped. It would be great if they were all listed in the securityUtility help

[una-tapa]

Todo: We will need to add more description under this line.
https://github.com/OpenLiberty/open-liberty/blob/integration/dev/com.ibm.ws.security.utility/resources/com/ibm/ws/security/utility/resources/UtilityOptions.nlsprops#L56

The description should prompt user to think about escaping special characters.
Kyle's original suggestion is great.

The following characters must be escaped for proper encoding [$, ...]
    For example pa$$W0rd should be provided as pa\$\$W0rd

As he suggests, we will need to provide more information regarding which characters need to be escaped.
Unfortunately it depends on the operating systems.. (It is different between Windows and Linux for example)

There is a neat trick to find out without looking up documentation.
In the command prompt, type "echo" followed by the password and see where the output started to differ. That's where we want the user to place the escape character. The following is the example on Ubuntu.

$ echo pa$$word
pa683word <===== OK until "pa"
$ echo pa$$word <== Added escape after "pa"
pa$ <=== OK until "pa$"
$ echo pa$$word <== Added escape after "pa$"
pa$$word <== Yes, this is the password I want securityUtility to encode

[dmuelle]

We will document the $echo strategy in the docs (OpenLiberty/docs#7623) so the command help can just refer to the documentation. Suggested update

If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded. 
Special characters and escape characters might vary according to your operating system. 
For example, on Unix systems, pa$$W0rd must be provided as pa$$W0rd. 
For more information, see the Open Liberty securityUtility encode documentation.

[dmuelle]

note that in my suggestion the backslash characters are being hidden by Github markdown. View the comment in edit mode to see the full example

[dudedev]

@una-tapa I would like to take this up.

[una-tapa]

Thank you @dudedev !

[dmuelle]

Docs are updated on draft: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/securityUtility-encode.html#pw

[dudedev]

@una-tapa @dmuelle Which option would you prefer the most?
Option 1:

Usage:
        securityUtility encode [options]

Description:
        Encode the provided text.

        If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded.
        Special characters and escape characters might vary according to your operating system.
        For example, on Unix systems, pa$$W0rd must be provided as pa\$\$W0rd.
        For more information, see the Open Liberty securityUtility encode documentation.


Options:
    --encoding=[xor|aes|hash]
        Specify how to encode the password. Supported encodings are xor, aes,
        and hash. The default encoding is xor.

Option 2: Prefixed with Note - before the text.
Example:

Usage:
        securityUtility encode [options]

Description:
        Encode the provided text.

        Note - If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded.
        Special characters and escape characters might vary according to your operating system.
        For example, on Unix systems, pa$$W0rd must be provided as pa\$\$W0rd.
        For more information, see the Open Liberty securityUtility encode documentation.


Options:
    --encoding=[xor|aes|hash]
        Specify how to encode the password. Supported encodings are xor, aes,
        and hash. The default encoding is xor.

Option 3 - Move the detailed description under textToEncode parameter

Example -

Usage:
        securityUtility encode [options]

Description:
        Encode the provided text.

        If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded.


Options:
    --encoding=[xor|aes|hash]
        Specify how to encode the password. Supported encodings are xor, aes,
        and hash. The default encoding is xor.
        
    textToEncode
        If no arguments are specified, the tool will enter the interactive
        mode; otherwise, the provided text will be encoded.
        Text with spaces must be fully quoted if specified as an argument.
        
        Note - If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded.
        Special characters and escape characters might vary according to your operating system.
        For example, on Unix systems, pa$$W0rd must be provided as pa\$\$W0rd.
        For more information, see the Open Liberty securityUtility encode documentation.

[una-tapa]

@dmuelle - The draft look great to me. Thank you.

[dudedev]

@una-tapa What is the next stage for this issue? Can it be closed?

[una-tapa]

@dudedev I thought it will be closed automatically with the release information which Liberty release it will be in. Please give it a couple of days.