Core Encryption Mechanism
The Warewolf lightweight execution engine uses AES-256-GCM encryption with keys stored in Azure Key Vault to safeguard sensitive data. On full (on-premises) Warewolf servers, Windows DPAPI protects values; Azure deployments cannot use DPAPI (it is machine-bound), so they use the Key Vault–backed AES approach instead.
Protected Assets
Encryption covers any configuration that stores secrets in a ConnectionString attribute, plus the secure server configuration and the license file:
- Source
.bitefiles (database, web, SharePoint credentials) —<Source ConnectionString="…"> - Elasticsearch logging source credentials (
ElasticsearchLoggingSource.bite) - Other
.biteconfig sources with a<Source>element and aConnectionStringattribute secure.config— the server security configuration (encrypted with AES before staging; see License File Encryption for the mechanism)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 the Key Vault inline (no separate setup script), generates/stores the AES key, encrypts every deployable source, optionally verifies decryption in memory, and wires 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 setup. Create the Key Vault and key using KeyVaultSetup.ps1 or KeyVaultSetup.azcli (use this only if you are not provisioning through Deploy-WwExecutionEngine.ps1, which does it inline).
Step 2 — Encrypt .bite files using Encrypt-Config.ps1:
- The first run with
-GenerateKes a new 256-bit key in Key Vault. - Subsequent runs (without
-GenerateKeys) encrypt only newly added plaintext or DPAPI values; values that are alreadyWFAES::d. To re-encrypt or rotate existingvalues, use-GenerateKeys(see Key Rotation).
# First-time setup: generate the key and encrypt all .bite files .\Encrypt-Config.ps1 -FilePath "C:\Warewolf\ewolf-prod" -SecretName "dp-keyring-v1"-GenerateKeys
# Later: encrypt newly added plaintext/DPAPI files using the existing key .\Encrypt-Config.ps1 -FilePath "C:\Warewolf\ewolf-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 ConnectionString="…"></c |
-VaultName |
Yes | Azure Key Vault name (e.g. kv-warewolf-prod). |
-SecretName |
Yes | Key Vault secret holding the AES key mate script has no default (the engineenv-var default is dp-keyring-v1; see Configuration Variables). |
-GenerateKeys |
No | Generate a NEW AES-256 key, store it as -)encrypt all files. ExistingWFAES:: values are decrypted with the current key, then re-encrypted with the new one. Cannot be combined with -Decrypt or -VerifyO |
-Decrypt |
No | Decrypt WFAES::/DPAPI ConnectionStrings back to plain text into an output directory(originals untouched). This writes p recovery/inspection — delete the outputdirectory after use. |
-VerifyOnly |
No | Decrypt every WFAES::/DPAPIong> to prove the Key Vault key works. Nofile (and no plaintext) is written. Read-only. |
-NonInteractive |
No | Never prompt; implies -NoBackup</cctory is supplied. Used byDeploy-WwExecutionEngine.ps1. |
-NoBackup |
No | Skip the pre-encryption backup prompt/st |
-OutputDirectory |
No | Explicit target for the backup (encrypt mode) or the decrypted files (decrypt mode); suppresses the prompt. |
Configuration Variables (runtime engine app settings)
| Variable | Required | Default | Purpose |
|---|---|---|---|
AZURE_KEYVAULT_NAME |
Yes | — | Enables encryption (omit to disable).</t |
KEYVAULT_SECRET_NAME |
No | dp-keyring-v1 |
Secret name holding the AES key ring.</t |
WorkflowsDirectory |
No | {BaseDir}/Resources |
Path to .bite files. |
License File Encryption
License files use an AES-256-CBC scheme — the same algorithm Warewolf Studio uses (mirrors
Dev2.Infrastructure Securs is a separate mechanism that doesnot use Key Vault and is handled by Protect-LicenseConfig.ps1 (shipped in the engine
application/publish directory, not the <code
Deploy-WwExecutionEngine.ps1 cose.secureconfig you supply into thepackage as-is — it does not run Protect-LicenseConfig.ps1. Encrypt the license file with
Protect-LicenseConfig.ps1 -Encrypt</colready protected.
Backup Behaviour
Before encrypting in place, Encrypt-Cock up the ), preservingsubdirectory structure; files keep their .bite files(interactive runs only). If confirmed, files are copied to a timestamped directory (default: the
source path with a date-time stamp appended,-15-14-30-45-12.bite extension. A custom path may be entered at the prompt.
Unattended runs (-NonInteractive</codekip the backup — operate on a copy.
Key Rotation
Rotate every 90 days (or immediately after arunning Encrypt-Config.ps1 with-GenerateKeys against the .bite files. The script decrypts existing WFAES::
values with the current key and re-encrypts pass.
.\Encrypt-Config.ps1 -FilePath "C:\Warkv-warewolf-prod" -SecretName "dp-keyring-v1" -GenerateKeys
Verifying a Deployment
Confirm the deployed key can decrypt every vplaintext 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 deployped backup directory (e.g.
Resources_<timestamp>) created by the backup prompt. (The script does not create
.bite.bakfiles.) - 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 DPed on the Windows machine that createdit. - Maintain an offline backup of the Kmaterial). Losing it makes every
WFAES::value unrecoverable. - Prerequisites: Pow CLI (
az login), andWindows (DPAPI detection/decryption during encryption is Windows-only). - This article is for version 1.0 of the scripts, as of 2026-06-22. See https://warewolf.io/release-notes.php
