W-23138895 Secure properties update

modules/ROOT/nav.adoc

@@ -51,6 +51,7 @@
 ** xref:vibes-skills.adoc[]
 ** xref:vibes-api-ai-create-spec.adoc[]
 ** xref:vibes-create-integrations.adoc[]
+** xref:vibes-secure-properties.adoc[]
 ** xref:vibes-run-multiple-integration-projects-locally.adoc[]
 ** xref:vibes-prompt-examples.adoc[]
 ** xref:troubleshoot-generative-ai.adoc[]

modules/ROOT/pages/int-create-secure-configs.adoc

@@ -13,6 +13,10 @@ Define configuration properties to secure and customize your Mule application co
 * Define and use variables instead of literal strings when setting values in the configuration XML.
 * Configure a variable for selecting different property files for a specific deployment environment, such as development, sandbox, or production.
 
+.How secure properties work
+image::int-secure-properties-overview-diagram.png[Diagram showing secure properties flow from runtime argument to global-configs.xml to encrypted properties file to flow references]
+
+For a guided, conversational approach to setting up secure properties, use MuleSoft Vibes. For additional information, see xref:vibes-secure-properties.adoc[].
 
 == Before You Begin
 
@@ -241,6 +245,19 @@ my-key-value \
 ----
 +
 IMPORTANT: Store your encryption key value (password) in a secure location. You'll need your key value later, when you deploy your application.
++
+TIP: To verify an encrypted value, decrypt it using the same tool with the `decrypt` command instead of `encrypt`:
++
+[source,terminal]
+----
+$ java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
+string \
+decrypt \
+Blowfish \
+CBC \
+my-key-value \
+"/MU0/xB/zoMPjxBA7/9X44Ad2H8O8AY5"
+----
 . In your properties file, add each encrypted property value within `![]` brackets.
 +
 .Example that replaces the unencrypted value `"mysensitivevalue"` with the encrypted value `"![/MU0/xB/zoMPjxBA7/9X44Ad2H8O8AY5]"`:
@@ -442,6 +459,55 @@ This name serves as the key for the encryption value (password) used to encrypt
 +
 Notice the `secure::` prefix to the key.
 
+[[edit-via-ui]]
+== Edit Secure Properties Configuration via Global Elements
+
+Instead of manually editing your project's XML, you can configure secure properties through Global Elements.
+
+To edit the secure properties configuration:
+
+. Open *Project Properties* > *Global Elements*.
++
+image:int-global-elements-panel-list.png["Global Elements panel with list of configurations including Secure Properties Config."]
++
+. Select *global-configs.xml* from the *Selected File* dropdown.
+. Find *Secure Properties Config* in the list.
+. Click the *...* menu (three dots) next to the configuration name.
+. Click *Edit*.
+
+The editor opens and you can modify these fields.
+
+image::int-secure-properties-form-editor.png["Form editor showing configurable fields for Secure Properties Config.", 75%, 75%]
+
+[%header,cols="20a,30a,50a"]
+|===
+| Field | Example Value | What It Controls
+
+| *Name*
+| Secure_Properties_Config
+| Element name referenced internally
+
+| *File*
+| ${env}.secure.properties
+| Which encrypted file to load (resolves per environment)
+
+| *Key*
+| ${encryption.key}
+| The decryption key placeholder (resolved from system property)
+
+| *Algorithm*
+| AES
+| Encryption algorithm (AES, Blowfish, DES, DESede, RC2)
+
+| *Mode*
+| CBC
+| Cipher mode (CBC, CFB, ECB, OFB)
+|===
+
+Changes you make in the editor automatically update the XML in `global-configs.xml`.
+
+The editor manages the configuration element. To change the actual encrypted values in `.secure.properties` files, use the secure-properties-tool JAR, edit the file directly, or ask MuleSoft Vibes to re-encrypt values. See xref:vibes-secure-properties.adoc[].
+
 [[test-deploy]]
 == Test Encrypted Properties in Your IDE
 
@@ -669,8 +735,46 @@ image::deploy-to-cloudhub-icon-with-deploy-json.png["Deploy to CloudHub rocket i
 +
 You can create properties or change the value of existing properties, for example, to fix some deployment errors.
 
+[[quick-reference]]
+== Quick Reference
+
+Use this table for quick access to common secure properties tasks and commands:
+
+[%header,cols="30a,70a"]
+|===
+| Task | Command / Location
+
+| Encrypt a value
+| `java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool string encrypt AES CBC <key> <value>`
+
+| Decrypt a value
+| `java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool string decrypt AES CBC <key> <encrypted-value>`
+
+| Reference encrypted property in XML
+| `${secure::property.name}`
+
+| Reference non-encrypted property in XML
+| `${property.name}`
+
+| Secure properties config element
+| `<secure-properties:config file="${env}.secure.properties" key="${encryption.key}">`
+
+| Pass encryption key locally
+| Add `-M-Dencryption.key=YourKey` to `mule.runtime.args` in `launch.json`
+
+| Pass encryption key in CloudHub
+| Add to Properties tab in Runtime Manager: `encryption.key=YourKey`
+
+| Switch environment
+| Pass `-M-Denv=qa` or `-M-Denv=prod` as runtime argument
+
+| Hide encryption key in CloudHub
+| Add encryption key name to `secureProperties` array in `mule-artifact.json`
+|===
+
 == See Also
 
+* xref:vibes-secure-properties.adoc[]
 * xref:int-global-config-elements.adoc[]
-* xref:mule-runtime::secure-configuration-properties.adoc[]
 * xref:int-run-mule-apps-with-properties.adoc[]
+* xref:mule-runtime::secure-configuration-properties.adoc[]

modules/ROOT/pages/int-run-mule-apps-with-properties.adoc

@@ -260,10 +260,164 @@ Reference these properties in your database configuration:
 </db:config>
 ----
 
+[[shared-encryption-keys-workspace]]
+== Configure Shared Encryption Keys Across a Workspace
+
+When you have multiple Mule projects in the same workspace that use the same encryption key, configure it once at the workspace level instead of duplicating it in each project's launch.json.
+
+Use the approach that better applies to your workflow and security requirements.
+
+* <<workspace-settings-approach,Workspace Settings>>: Configure the encryption key in 
+  your workspace settings.json. All projects inherit the setting 
+  automatically.
+
+* <<environment-variable-approach,Environment Variable>>: Store the key as an OS environment variable 
+  in your shell profile. Use this method to keep 
+  encryption keys completely out of version-controlled files or if you need 
+  machine-specific configuration.
+
+* <<multi-root-workspace-approach,Multi-Root Workspace>>: Configure the encryption key directly in a 
+  .code-workspace file. Use this approach when working with 
+  multiple Mule projects open simultaneously in a multi-root 
+  workspace. For information about multi-root workspaces, see 
+  [link to VS Code docs or existing ACB topic].
+
+[[workspace-settings-approach]]
+=== Use Workspace Settings
+
+Add the encryption key to your workspace `settings.json` so all projects inherit it.
+
+. In your `.code-workspace` file or `.vscode/settings.json` at the workspace root, add the key.
++
+[source,json]
+----
+{
+  "settings": {
+    "mule.runtime.defaultArguments": "-M-Dencryption.key=MuleSecureKey024"
+  }
+}
+----
++
+. Reference the shared setting in each project's `launch.json`.
++
+[source,json]
+----
+{
+  "mule.runtime.args": "${config:mule.runtime.defaultArguments}"
+}
+----
+
+[[environment-variable-approach]]
+=== Use an Environment Variable
+
+Set the key as an OS environment variable in your shell profile (`~/.zshrc` or `~/.bash_profile`)
+
+. Run this command. 
++
+[source,bash]
+----
+export MULE_ENCRYPTION_KEY="MuleSecureKey024"
+----
++
+. Reference the key in the workspace `launch.json`:
++
+[source,json]
+----
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "mule-xml-debugger",
+      "request": "launch",
+      "name": "Debug with Environment Variable",
+      "mule.project": "${workspaceFolder}",
+      "mule.home": "${config:mule.homeDirectory}",
+      "mule.runtime.args": "${config:mule.runtime.defaultArguments} -M-Dencryption.key=${env:MULE_ENCRYPTION_KEY}"
+    }
+  ]
+}
+----
+
+[[multi-root-workspace-approach]]
+=== Use a Shared Launch Configuration in Multi-Root Workspaces
+
+To configure a shared encryption key in a multi-root workspace:
+
+. Open or create your `.code-workspace` file.
+. Add a `launch` section to the workspace configuration with the 
+   encryption key:
++
+[source,json]
+----
+{
+  "folders": [  // <1>
+    { "path": "salesforce-sync" },
+    { "path": "netsuite-integration" },
+    { "path": "slack-notifications" }
+  ],
+  "launch": {  // <2>
+    "configurations": [
+      {
+        "type": "mule-xml-debugger",
+        "request": "launch",
+        "name": "Run Mule App (Shared Key)",  // <3>
+        "noDebug": true,
+        "mule.projects": ["${workspaceFolder}"],
+        "mule.runtime.args": "${config:mule.runtime.defaultArguments} -M-Dencryption.key=MuleSecureKey024"  // <4>
+      }
+    ]
+  }
+}
+----
+<1> List the relative paths to each Mule project in your workspace
+<2> Add the launch configuration section with the shared encryption key
+<3> Name that appears in the Run and Debug dropdown
+<4> Replace `MuleSecureKey024` with your encryption key
++
+. Save the workspace file.
+
+When you select *Run Mule App (Shared Key)* from the Run and Debug 
+dropdown, Code Builder applies the shared encryption key to whichever 
+project is active.
+
+=== Protect Workspace Configuration in .gitignore
+
+If your workspace settings contain sensitive values, add them to `.gitignore`:
+
+[source,gitignore]
+----
+# Workspace config (may contain encryption key)
+*.code-workspace
+.vscode/settings.json
+----
+
+[[key-rotation-workspace]]
+=== Re-encrypt All Projects After Key Rotation
+
+When you rotate the shared key, re-encrypt every secure properties file across all projects:
+
+[source,bash]
+----
+NEW_KEY="NewSharedKey2025!"
+
+# For each project in the workspace:
+for project in salesforce-sync netsuite-integration slack-notifications; do
+  FILE="$project/src/main/resources/prod.secure.properties"
+  if [ -f "$FILE" ]; then
+    echo "Re-encrypting: $FILE"
+    # Decrypt each value with old key, re-encrypt with new key
+    # (or use a local backup file with plaintext to re-encrypt)
+  fi
+done
+----
+
+Then update the single workspace-level key reference and all projects work immediately.
+
 == See Also
 
 * xref:int-create-secure-configs.adoc[]
 * xref:int-run-multiple-mule-apps.adoc[]
-* xref:ref-mule-settings.adoc#setting-mule-args[]
+* xref:ref-mule-settings.adoc#setting-mule-args[Mule › Runtime: Default Arguments]
 * xref:int-global-config-elements.adoc[]
+* xref:start-workspaces.adoc[]
 * xref:mule-runtime::configuring-properties.adoc[]