Merge pull request #7626 from OpenLiberty/7623-security

add explanation

modules/reference/pages/command/securityUtility-encode.adoc

@@ -19,7 +19,12 @@ The `securityUtility encode` command supports plain text obfuscation for Open Li
 This command obfuscates text that you provide, such as a password, based on the type that is specified.
 If no text is provided, the command enters interactive mode.
 Interactive mode prompts you to enter and confirm your text input, rather than provide text on the same line as the command.
-Text with spaces must be put in quotation marks.
+Enclose any text with spaces in quotation marks.
+If your password includes special characters, you must escape each special character to help ensure that the password is properly encoded. For more information, see <<pw,Check passwords for special characters>>
+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 about limits to password encryption, see xref:ROOT:password-encryption.adoc[Password encryption limitations].
 
 == Usage examples
@@ -111,3 +116,27 @@ The following exit codes are available for the `securityUtility encode` command:
 |5
 |This code indicates that the file already exists.
 |===
+
+
+[#pw]
+== Check passwords for special characters
+
+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`.
+
+To check whether your password includes any characters that your operating system considers to be special characters, you can run the `echo` command.
+
+On the command line, type `echo` followed by the password and review the output to determine whether it differs from your specified password. If any characters are changed, you must escape the characters.  The following example is for 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
+// Escaping each special character individually provides the correct password to encode
+
+$ securityUtility encode pa\$\$word
+----