Credential Hardening

v8.7.4

IEM v8.7.4 adds optional AES-256 hardening for credentials stored in the database (SMTP passwords, API keys, OAuth secrets).

This is optional. IEM works without it — credentials continue to use the existing storage mechanism.

For token-based links, see Token-Based Links.

Setup

Step 1: Generate a Key

php tools/generate-keys.php

This outputs two keys. For credential hardening, you need SENDSTUDIO_ENC_KEY:

define('SENDSTUDIO_ENC_KEY', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

Step 2: Add to config.php

Paste the line into ~/admin/includes/config.php.

Step 3: Run the Upgrade

Navigate to the admin panel. If pending upgrades are detected, the upgrade page will appear automatically. Run the upgrade — it prepares the database for AES-256 values.

That’s it. Existing credentials are upgraded to AES-256 the next time they are saved. You can re-save credentials through the admin UI (e.g. Settings > Email Settings) to upgrade them immediately.

How It Works

Algorithm: AES-256-CBC + HMAC-SHA256
On read: Auto-detects format and returns the correct value
On save: Hardens with AES-256 if the key is available

Credentials are upgraded to AES-256 the next time they are saved. No separate migration step is needed.

What Gets Hardened

Credentials stored in the database, including:

SMTP passwords
Bounce server passwords
API keys
OAuth client secrets

Key Safety

Adding AES-256 Hardening After Upgrade

If you upgrade to v8.7.4 first and add the key later:

Run php tools/generate-keys.php
Add SENDSTUDIO_ENC_KEY to ~/admin/includes/config.php
Re-save credentials through the admin UI to upgrade them to AES-256 (e.g. Settings > Email Settings for SMTP passwords)

Troubleshooting

Symptom	Cause	Fix
SMTP, bounce processing, and OAuth all fail simultaneously	Key changed or removed	Restore the original key, or re-enter all passwords in the admin UI
”SENDSTUDIO_ENC_KEY not configured” in log	Key not in config.php	Add key from `php tools/generate-keys.php`