Connection String Encryption¶

Section: Security Configuration | Article 11
Audience: IT Administrators
Last Updated: 2026-04-07

Overview¶

After the setup wizard completes, your database connection string (including the password) is stored in the RP-PAM configuration file (rppam.config). By default, this value is in plain text. This article walks you through encrypting it using RP-PAM's built-in Content Encryption Key (CEK) so that credentials are protected at rest.

This is a critical security step. Do not skip it for production deployments.

Why This Matters¶

If an attacker gains read access to the RP-PAM configuration file (through a backup leak, file-share misconfiguration, or compromised admin workstation), a plain-text connection string gives them direct access to your RP-PAM database. Encrypting the connection string means the value is useless without the corresponding CEK, which is stored separately in the keys directory with restricted permissions.

How It Works¶

RP-PAM uses a two-tier key hierarchy:

Content Encryption Key (CEK) — Encrypts and decrypts sensitive configuration values.
Key Encryption Key (KEK) — Wraps (encrypts) the CEK itself.

When you encrypt a connection string, RP-PAM: 1. Reads the CEK from disk (which is stored encrypted under the KEK). 2. Unwraps the CEK using the KEK. 3. Encrypts your plain-text value with the CEK using AES-256-GCM. 4. Returns a Base64-encoded cipher text string prefixed with ENC:. 5. You paste this ENC:... string into rppam.config. At runtime, RP-PAM decrypts it automatically.

Prerequisites¶

Requirement	Details
RP-PAM installed and setup wizard completed	The CEK must exist before you can encrypt values
Access to the RP-PAM server	Administrator (Windows) or sudo (Linux)
Current plain-text connection string	Found in `rppam.config`

Step 1 — Locate Your Configuration File¶

Platform	Config File Path
Windows	`C:\ProgramData\Ravenphyre\RP-PAM\config\rppam.config`
Linux	`/etc/rppam/rppam.config`
Docker	`/etc/rppam/rppam.config` (inside the container, or on the mapped volume)

Open the file and find the current plain-text connection string. It will look similar to:

{
  "database": {
    "provider": "mssql",
    "connectionString": "Server=db-server.example.com;Database=rppam;User Id=rppam_write;Password=WriteP@ssw0rd!2026;Encrypt=True;TrustServerCertificate=False;"
  }
}

Copy the entire connection string value (everything between the quotes after "connectionString":). You will need it in Step 3.

Step 2 — Verify the CEK Is Initialised¶

Before encrypting, confirm the CEK exists.

Windows (PowerShell)¶

& "C:\Program Files\Ravenphyre\RP-PAM\rppam.exe" cek status

Expected output:

CEK Status: Initialised
KEK Status: Initialised
Algorithm:  AES-256-GCM
Key Store:  C:\ProgramData\Ravenphyre\RP-PAM\keys\

Linux (Bash)¶

sudo /opt/rppam/rppam cek status

Expected output:

CEK Status: Initialised
KEK Status: Initialised
Algorithm:  AES-256-GCM
Key Store:  /etc/rppam/keys/

If the CEK is not initialised, the setup wizard was not completed. Run the setup wizard first (see Setup Wizard).

Step 3 — Encrypt the Connection String¶

Windows (PowerShell)¶

& "C:\Program Files\Ravenphyre\RP-PAM\rppam.exe" cek encrypt --value "Server=db-server.example.com;Database=rppam;User Id=rppam_write;Password=WriteP@ssw0rd!2026;Encrypt=True;TrustServerCertificate=False;"

Expected output:

Encrypted value:
ENC:AQICAHh...long_base64_string...==

Linux (Bash)¶

sudo /opt/rppam/rppam cek encrypt \
    --value "Server=db-server.example.com;Database=rppam;User Id=rppam_write;Password=WriteP@ssw0rd!2026;Encrypt=True;TrustServerCertificate=False;"

Docker¶

docker exec -it rppam /opt/rppam/rppam cek encrypt \
    --value "Server=db-server.example.com;Database=rppam;User Id=rppam_write;Password=WriteP@ssw0rd!2026;Encrypt=True;TrustServerCertificate=False;"

Copy the entire output starting with ENC: (including the ENC: prefix).

Security: The --value parameter appears in your shell history. After completing this process, clear your shell history: - PowerShell: Clear-History - Bash: history -c && history -w

Step 4 — Update the Configuration File¶

Replace the plain-text connection string with the encrypted value.

Windows (PowerShell)¶

Open the configuration file in a text editor:

notepad "C:\ProgramData\Ravenphyre\RP-PAM\config\rppam.config"

Linux (Bash)¶

sudo nano /etc/rppam/rppam.config

Find the connectionString field and replace the plain-text value with the encrypted value:

Before:

{
  "database": {
    "provider": "mssql",
    "connectionString": "Server=db-server.example.com;Database=rppam;User Id=rppam_write;Password=WriteP@ssw0rd!2026;Encrypt=True;TrustServerCertificate=False;"
  }
}

After:

{
  "database": {
    "provider": "mssql",
    "connectionString": "ENC:AQICAHh...long_base64_string...=="
  }
}

Save the file and close the editor.

Step 5 — Restart RP-PAM¶

The service must be restarted to pick up the new encrypted value.

Windows (PowerShell)¶

Restart-Service -Name "RavenphyreRpPam"

Linux (Bash)¶

sudo systemctl restart rppam

Docker¶

docker restart rppam

Step 6 — Verify the Service Starts Successfully¶

After the restart, confirm RP-PAM can decrypt the connection string and connect to the database.

Windows (PowerShell)¶

# Check service status
Get-Service -Name "RavenphyreRpPam"

# Check health endpoint
Invoke-RestMethod -Uri "https://localhost:7101/health" -SkipCertificateCheck

Linux (Bash)¶

# Check service status
sudo systemctl status rppam

# Check health endpoint
curl -sk https://localhost:7101/health | python3 -m json.tool

Expected health response:

{
    "status": "healthy",
    "version": "1.0.0",
    "uptime": "00:00:15"
}

If the status is healthy, the encrypted connection string is working correctly.

Encrypting Additional Values¶

You can encrypt any sensitive value in rppam.config, not just the connection string. Common values to encrypt:

Value	Config Path
Database connection string	`database.connectionString`
Redis connection string	`redis.connectionString`
SMTP password	`notifications.smtp.password`
AI provider API key	`ai.apiKey`
Webhook secrets	`notifications.webhooks[].secret`

Use the same cek encrypt command for each value and replace the plain-text entry with the ENC: output.

Decrypting a Value (For Debugging)¶

If you need to view the original plain-text value for troubleshooting:

Windows (PowerShell)¶

& "C:\Program Files\Ravenphyre\RP-PAM\rppam.exe" cek decrypt --value "ENC:AQICAHh...=="

Linux (Bash)¶

sudo /opt/rppam/rppam cek decrypt --value "ENC:AQICAHh...=="

Warning: Only decrypt values when actively troubleshooting. Do not store or log the decrypted output.

Troubleshooting¶

Symptom	Cause	Resolution
`cek encrypt` returns "CEK not initialised"	Setup wizard was not completed	Run the setup wizard (see Setup Wizard)
Service fails to start after replacing the connection string	Encrypted value was truncated or corrupted	Ensure you copied the complete `ENC:...` string including the `ENC:` prefix and trailing `==`
Service starts but health returns "unhealthy" with database error	Wrong value was encrypted, or original plain-text string was incorrect	Decrypt the value to verify it matches your expected connection string
"Access denied" when running `cek encrypt`	Insufficient permissions to read key material	Run as Administrator (Windows) or with `sudo` (Linux)
"Key material not found" error	Keys directory is missing or empty	Check that the keys directory exists and contains files. If lost, you must re-run the setup wizard on a fresh installation
Shell history contains the plain-text password	Password was visible in the `--value` parameter	Clear history: PowerShell `Clear-History`, Bash `history -c && history -w`

Next Steps¶

Online License Activation — Activate your license for automatic check-ins
Service Accounts — Configure the three-role service account model
Config Reference — Full reference for all rppam.config settings