Security – Encryption

Core Encryption Mechanism

The Warewolf lightweight execution engine uses AES-256-GCM with keys stored in Azure Key Vault to safeguard sensitive .bite ConnectionString values. Separately, secure.config and Warewolf License.secureconfig use the engine’s fixed AES-256-CBC mechanism. On full (on-premises) Warewolf servers, Windows DPAPI protects values; Azure deployments cannot rely on DPAPI (it is machine-bound), so deployable sources must be converted to the Key Vault-backed WFAES approach.

Protected Assets

Encryption covers any configuration that stores secrets in a ConnectionString attribute, plus the secure server configuration and the license file:

Source .bite files (database, web, SharePoint credentials) — <Source ConnectionString="…">
Elasticsearch logging source credentials (ElasticsearchLoggingSource.bite)
Other .bite config sources with a <Source> element and a ConnectionString attribute
secure.config — the server security configuration (AES-encrypted before staging using the engine’s fixed AES-256-CBC mechanism; this does not use Key Vault)
Warewolf License.secureconfig — the license file (separate AES-256-CBC mechanism; see License File Encryption below)

Encryption Format (`.bite` ConnectionStrings)

Encrypted ConnectionString values use this structure:

WFAES::{Base64( [12-byte nonce][ciphertext][16-byte GCM tag] )}

Key characteristics:

The WFAES:: prefix makes the value invalid base64 on its own, so it is never misinterpreted as a DPAPI value on a machine without the AES hook.
AES-256-GCM is authenticated encryption — any tampering is detected at decrypt time.
At runtime the engine fetches the key from Key Vault once per cold start and decrypts in memory; decrypted secrets are never written to disk by the engine.

Deployment Paths

There are two ways to provision Key Vault and encrypt sources. The orchestrated path is recommended.

Recommended — orchestrated (`Deploy-WwExecutionEngine.ps1`)

Deploy-WwExecutionEngine.ps1 provisions all infrastructure and, when -EncryptResources is supplied, creates or wires the Key Vault inline, generates/stores the AES key, encrypts every deployable source, optionally verifies decryption in memory, and writes the runtime app settings.

# First deploy — provision the vault + key and encrypt all sources, verifying in memory .\Deploy-WwExecutionEngine.ps1 ` -ResourceGroup DEV2 -Location southafricanorth ` -StorageAccount stwwenginetestv1 -AppName wwenginetestv1 ` -PublishPath 'D:\ExecutionEngine\AzureFunctionsPackage' ` -EncryptResources:$true -VerifyDecryption -GenerateNewKey ` -KeyVaultName WWExecutionEngine -KeyVaultSecretName WWExecutionEngineTestSecret

-EncryptResources is optional and defaults to OFF. The intended workflow is encrypt once, then deploy as-is: on later deploys leave -EncryptResources off — the sources are already encrypted and are staged unchanged — but still pass -KeyVaultName/-KeyVaultSecretName so the engine’s app settings and managed-identity role are wired for runtime decryption.

Manual — step by step

Step 1 — Infrastructure / Key Vault wiring. Use KeyVaultSetup.azcli to create the Key Vault, enable the Function App managed identity, grant roles, and write the app settings; or use KeyVaultSetup.ps1 when the Key Vault and Function App already exist and you only need the RBAC/app-setting wiring. Neither script creates the AES key material itself — that happens when you run Encrypt-Config.ps1 -GenerateKeys. Use these setup scripts only if you are not provisioning through Deploy-WwExecutionEngine.ps1, which can do the wiring inline.

Step 2 — Encrypt .bite files using Encrypt-Config.ps1:

The first run with -GenerateKeys generates a new 256-bit AES key in Key Vault and encrypts all matching .bite files.
Subsequent runs (without -GenerateKeys) encrypt only newly added plaintext or DPAPI values; values that are already WFAES::-encrypted are skipped. To re-encrypt or rotate existing values, use -GenerateKeys (see Key Rotation).

# First-time setup: generate the key and encrypt all .bite files .\Encrypt-Config.ps1 ` -FilePath "C:\Warewolf\Resources" ` -VaultName "kv-warewolf-prod" ` -SecretName "dp-keyring-v1" ` -GenerateKeys

# Later: encrypt newly added plaintext/DPAPI values using the existing key .\Encrypt-Config.ps1 ` -FilePath "C:\Warewolf\Resources" ` -VaultName "kv-warewolf-prod" ` -SecretName "dp-keyring-v1"

`Encrypt-Config.ps1` Parameters

Parameter	Required	Purpose
`-FilePath`	Yes	A single `.bite` file, or a folder searched recursively for `.bite` files. Files without a `<Source>` element with a `ConnectionString` attribute are silently skipped.
`-VaultName`	Yes	Azure Key Vault name (e.g. `kv-warewolf-prod`).
`-SecretName`	Yes	Name of the Key Vault secret holding the AES key material. Required — `Encrypt-Config.ps1` has no default.
`-GenerateKeys`	No	Generate a NEW AES-256 key, store it as a new secret version under `-SecretName`, and re-encrypt all files. Existing `WFAES::` values are decrypted with the current key, then re-encrypted with the new one. Cannot be combined with `-Decrypt` or `-VerifyOnly`.
`-Decrypt`	No	Decrypt `WFAES::`/DPAPI `ConnectionString` values back to plain text into an output directory (originals untouched). This writes plaintext to disk for recovery/inspection — delete the output directory after use. Cannot be combined with `-GenerateKeys`.
`-VerifyOnly`	No	Decrypt every `WFAES::`/DPAPI `ConnectionString` in memory to prove the Key Vault key works. No file (and no plaintext) is written. Read-only. Cannot be combined with `-GenerateKeys`.
`-NonInteractive`	No	Never prompt. Used by `Deploy-WwExecutionEngine.ps1`. In practice unattended runs skip the pre-encryption backup prompt entirely; in `-Decrypt` mode, pair it with `-OutputDirectory` to control where plaintext is written.
`-NoBackup`	No	Skip the pre-encryption backup prompt/step.
`-OutputDirectory`	No	Explicit target directory for `-Decrypt` output; suppresses the output-directory prompt. The current script implementation does not use this parameter for the interactive pre-encryption backup path.

Configuration Variables (runtime engine app settings)

Variable	Required	Default	Purpose
`AZURE_KEYVAULT_NAME`	Yes (for WFAES-encrypted deployments)	—	Enables Key Vault-backed decryption of `WFAES::` connection strings at runtime. Leave it unset only when no WFAES encryption is in use.
`KEYVAULT_SECRET_NAME`	No	`dp-keyring-v1`	Secret name holding the AES key ring. The runtime has this default, but the deployment/encryption scripts still expect you to pass the secret name explicitly.
`WorkflowsDirectory`	No	`{BaseDir}/Resources`	Path to `.bite` files. The deployment scripts stage workflows into `Resources` and normally rely on this default.

License File Encryption

License files use an AES-256-CBC scheme — the same algorithm Warewolf Studio uses — mirroring Dev2.Infrastructure SecurityEncryption. This is a separate mechanism that does not use Key Vault and is handled by Protect-LicenseConfig.ps1, which ships with the engine application/publish output rather than this deployment-scripts zip.

Deploy-WwExecutionEngine.ps1 copies whatever Warewolf License.secureconfig you supply into the package as-is — it does not run Protect-LicenseConfig.ps1. Encrypt the license file before deployment (for example with Protect-LicenseConfig.ps1 -Encrypt) and then pass the already-protected file via -LicenseConfigPath.

Backup Behaviour

Before encrypting in place, Encrypt-Config.ps1 prompts whether to back up the .bite files (interactive runs only). If confirmed, files are copied to a timestamped directory (default: the source path with a date-time stamp appended, e.g. Resources_2026-06-15-14-30-45-12), preserving subdirectory structure; files keep their .bite extension. A custom path may be entered at the prompt. Unattended runs (-NonInteractive) skip the backup.

Key Rotation

Rotate every 90 days (or immediately after a suspected compromise) by running Encrypt-Config.ps1 with -GenerateKeys against the .bite files. The script decrypts existing WFAES:: values with the current key and re-encrypts them with the new key in one pass.

.\Encrypt-Config.ps1 ` -FilePath "C:\Warewolf\Resources" ` -VaultName "kv-warewolf-prod" ` -SecretName "dp-keyring-v1" ` -GenerateKeys

Verifying a Deployment

Confirm the deployed key can decrypt every value in memory without writing plaintext by using -VerifyOnly (or Deploy-WwExecutionEngine.ps1 -VerifyDecryption, which calls it):

.\Encrypt-Config.ps1 ` -FilePath "C:\Warewolf\Resources" ` -VaultName "kv-warewolf-prod" ` -SecretName "dp-keyring-v1" ` -VerifyOnly

Important Notes

After verifying an encrypted deployment works, delete any timestamped backup directory (for example Resources_<timestamp>) created by the backup prompt. The script does not create .bite.bak files.
If you used -Decrypt, delete the decrypted output directory — it contains plain-text credentials.
DPAPI-encrypted values must be re-encrypted to WFAES:: before deploying to Azure/Linux. DPAPI is machine-bound, so a DPAPI value can only be decrypted on the Windows machine that created it.
Maintain an offline backup of the Key Vault key material. Losing it makes every WFAES:: value unrecoverable.
Prerequisites: PowerShell 7+, Azure CLI logged in via az login, and Windows for DPAPI detection/decryption during encryption.
This article reflects the Warewolf-ExecutionEngine-Deployment-Scripts-v2.1 bundle (README: Warewolf Version 3.0.2.79, stamped 2026-06-22). Download current releases from https://warewolf.io/release-notes.php