New Bond Encryption Key With Version 26.1.0.
search cancel

New Bond Encryption Key With Version 26.1.0.

book

Article ID: 453015

calendar_today

Updated On:

Products

Automic Automation Automic Continuous Delivery Automation

Issue/Introduction

  1. From Bond 26.1.0 onwards, all at-rest secrets stored in the database—AE background-user passwords, report database connection passwords, execution passwords, and queue authentication keys—are protected by a per-installation AES-256 key. This key is stored in web.config rather than being compiled into the binary.

    Every upgrade from an earlier release requires three steps:

    1. Configure the key in every config file before starting Bond.

    2. Back up the database.

    3. Run the database migration to re-encrypt existing rows to the new format.

    Security Note

    Bond will refuse to start if BondEncryptionKey is missing, invalid, or set to a known default placeholder. A clear error message will be displayed at startup.

    Prerequisites

    Ensure the following requirements are met before running the migration:

    • System State: All Bond nodes must be stopped.

    • Permissions: Write access to web.config is required on every cluster node.

    • Tools: Access to either the RamiusMigrationTool or the standalone DataMigrator (Note: Please verify the "Step 5" reference here based on your broader document).

    • Environment: PowerShell 5.1 or later (ships with Windows Server 2016+).

Environment

 

  • The environment must be running Bond version 26.1.0 or higher.

  • The system requires PowerShell 5.1 or later.

  • Administrators need write access to cluster configuration files and access to either the RamiusMigrationTool or the standalone DataMigrator.

 

Cause

Product enhancement.

Resolution

Step 1: Generate a unique key (required once per installation)

Run the following PowerShell snippet on any machine. It only generates random bytes; nothing is written to disk.

PowerShell

Compatible with PowerShell 5.1 / .NET Framework 4.x

$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$key = [Convert]::ToBase64String($bytes)
Write-Host "Your BondEncryptionKey:"
Write-Host $key
Example Output:
###.####.####.####

Important: Save the key immediately
Store the value in a password manager or secrets vault before proceeding. If it is lost after encryption, the protected values in the database cannot be recovered. Do not use any known default or placeholder value, as Bond will reject these on startup.

Step 2: Configure web.config on every node

Open WebUI\web.config (relative to your installation directory) on each cluster node and replace the placeholder with the key from Step 1:

<!-- Before -->
<add key="BondEncryptionKey" value="KEY_FROM_STEP_1"/>

<!-- After -->
<add key="BondEncryptionKey" value="ENCRYPTED_KEY_WILL_SHOW_UP_HERE"/>

Automating via PowerShell To automate this across multiple nodes, save the following as Set-BondEncryptionKey.ps1:

param(
    [Parameter(Mandatory=$true)] [string]$ConfigPath,
    [Parameter(Mandatory=$true)] [string]$Key
)

$xml  = [xml](Get-Content $ConfigPath -Encoding UTF8)
$node = $xml.SelectSingleNode("/configuration/appSettings/add[@key='BondEncryptionKey']")

if ($node -eq $null) {
    Write-Error "'BondEncryptionKey' not found in $ConfigPath. Ensure Bond 26.1.0 is deployed."
    exit 1
}

$node.SetAttribute("value", $Key)
$xml.Save($ConfigPath)
Write-Host "BondEncryptionKey updated in $ConfigPath"

Usage (run once per node):

$key = "ENCRYPTED_KEY_WILL_SHOW_UP_HERE" .\Set-BondEncryptionKey.ps1 -ConfigPath "C:\Automic\Release.Manager\WebUI\web.config" -Key $key

Cluster Requirement All nodes share the same database and must use the exact same key.

  • Node 1: web.config uses BondEncryptionKey = ENCRYPTED_KEY_WILL_SHOW_UP_HERE

  • Node 2: web.config uses BondEncryptionKey = ENCRYPTED_KEY_WILL_SHOW_UP_HERE

  • Both nodes point to the Shared Database (v2: encrypted secrets).

Step 3: Configure migration tool config files

The database migration can be run in two ways (see Step 5). Both tools embed the migration engine and read BondEncryptionKey from their respective config files. Set the identical key value in whichever tool you choose to use.

Option A: Ramius Upgrade Tool (Recommended for full upgrades) The Ramius Upgrade Tool runs the database migration in-process as part of its upgrade workflow. It reads the key from RamiusUpgradeTool.exe.config.

Config File Path: Utilities\RamiusUpgradeTool\RamiusUpgradeTool.exe.config

.\Set-BondEncryptionKey.ps1 `
    -ConfigPath "C:\Automic\Tools\RamiusUpgradeTool\RamiusUpgradeTool.exe.config" `
    -Key $key

Option B: Standalone DataMigrator Users who run the DataMigrator independently of the Ramius Upgrade Tool must set the key in DataMigrator.exe.config.

Config File Path: Utilities\DataMigrator\DataMigrator.exe.config

.\Set-BondEncryptionKey.ps1 `
    -ConfigPath "C:\Automic\Tools\DataMigrator\DataMigrator.exe.config" `
    -Key $key

Startup Guard

Both the Ramius Upgrade Tool and the DataMigrator (GUI and command-line) validate BondEncryptionKey before any migration runs. A clear error message is shown if the key is missing or set to a known default placeholder.

Step 4: Back up the database (Required before migration)

The migration re-encrypts secrets permanently and cannot be reversed without restoring a backup. Take a full database backup now and verify it is restorable.

Procedure:

  1. Stop all Bond nodes (if not already stopped).

  2. Take a full backup of the Bond database using your standard DBA procedure (SQL Server, Oracle, or PostgreSQL).

  3. Confirm the backup file is complete and stored in a safe location.

Warning: Only continue to Step 5 once the backup is completely verified.

Step 5: Run the database migration

Choose the tool that matches your workflow:

Option A: Via Ramius Upgrade Tool (Recommended)

The Ramius Upgrade Tool performs a complete upgrade: it migrates the web.config, installs new files, and runs the database migration automatically as part of its workflow. No separate DataMigrator run is needed.

  1. Launch the tool via Utilities\RamiusUpgradeTool\RamiusUpgradeTool.exe.

  2. Complete the upgrade wizard. The tool upgrades web.config (including injecting BondEncryptionKey from the new installation) and runs all pending database migration scripts, including 2610/01_ReEncryptSecretsWithInstallationKey.

Option B: Standalone DataMigrator

Use this option when you manage the web.config upgrade separately and only need to run the database migration.

  1. Launch the tool via Utilities\DataMigrator\DataMigrator.exe.

  2. Browse to your configuration file. The default path is C:\Automic\Release.Manager\WebUI\customer.config.

  3. Click Test Connection to confirm Bond can reach the database.

  4. Click Migrate to run all pending scripts, including 2610/01_ReEncryptSecretsWithInstallationKey.

Migration Details

The migration script re-encrypts the following database columns:

TableColumnScope
A_ClientInfoPasswordHashShared
A_ClientInfoReportDbConnectionsShared (JSON, per-password field)
{prefix}ExecutionOwnerPasswordPer-client
{prefix}ExecutionTmplPasswordPer-client
{prefix}QueueAuthenticationKeyPer-client

Idempotent Execution

Rows already in v2: format are silently skipped. The migration is safe to run multiple times or on a partially migrated database.

Step 6: Start Bond and verify

Start Bond normally on all nodes. On startup, Bond validates the key and will fail immediately with a clear error message if:

  • BondEncryptionKey is missing from web.config.

  • The value is not valid Base64.

  • The value is not exactly 32 bytes (256 bits).

  • The value is a known default placeholder.

Verification Checklist

  1. Log in to Bond.

  2. Open Setup > Background User for each client and confirm the AE background user is shown correctly (Bond decrypts PasswordHash to test the AE connection).

  3. Open any client with Report DB configured; the report database should connect normally.

  4. Execute a deployment that uses a saved execution password; it should not prompt for re-entry.

Additional Information

Protected custom properties (No manual action required) Protected custom property values are not re-encrypted by the migration script. They are re-encrypted automatically the next time each value is saved through the normal Bond UI. Existing v1 values remain readable in the meantime because the decryption layer handles both the old and new formats transparently.

Rollback:

Always restore from a database backup The migration re-encrypts secrets permanently using the new key. There is no in-tool undo. The only safe rollback path is to restore the database backup taken in Step 4 and then redeploy the previous Bond release.

To roll back after a migration:

  1. Stop all Bond nodes immediately.

  2. Restore the database backup taken in Step 4 using your standard DBA procedure.

  3. Verify the restored database is consistent.

  4. Redeploy the previous Bond release.

  5. Start Bond.

Warning:

Do not attempt a partial rollback Reverting only the application binaries without restoring the database leaves the database in the new v2: format, which the old application cannot decrypt. Always restore both the application and the database together.

Key rotation (Future) If the key must be rotated (e.g., web.config was leaked), please contact support. The standard database migration tool’s idempotency check relies on the v2: prefix and does not verify which key was used. Therefore, a full key rotation requires a custom script that decrypts rows with the old key and re-encrypts them with the new one. This functionality is currently out of scope for the 26.1.0 release.

Powered by Wolken Software