Skip to content

08 Security and Storage

Jump to bottom
Mark Todd edited this page Aug 2, 2026 · 1 revision

Security and Storage

MQTTProbe encrypts broker passwords and certificate material at rest. Plaintext passwords never appear in appsettings.json.

What is stored where

Data Location
Connection profiles, preferences appsettings.json under the config root (passwords stripped)
Broker passwords Encrypted secret store (not in appsettings.json)
Client certificate blobs certificates/cert-{id}.bin under the data root (AES-256-GCM)
Certificate envelope (AES key, stored PFX password) Same secret store as passwords
Web Data Protection keys config/dp-keys/
Web secrets file config/secrets.dat
Desktop secrets secrets/ under the config root, plus an OS master key
Plugins Host-specific (see below)

Where your data lives

The config root is different for each platform.

Web and Docker

Item Path
Config root {ContentRoot}/config
Docker volume mqttprobe-config mounted at /app/config
Plugins volume mqttprobe-plugins mounted at /app/Plugins

Docker volumes survive container restarts and image upgrades. See Docker Deployment for Compose details.

Desktop (Linux and macOS)

Shipped Linux and macOS desktop builds use the Photino desktop host.

Item Path
Config root (Linux/macOS) ~/.config/mqttprobe (or $XDG_CONFIG_HOME/mqttprobe)
Config root (Windows Photino, if you run that build) %USERPROFILE%\.config\mqttprobe

On Windows Photino this is .config under your profile, not %APPDATA%. The recommended Windows desktop install (MQTTProbe-win-Setup.exe) is the MAUI build below, not Photino.

Windows and Android apps (MAUI)

The Windows desktop app (installer MQTTProbe-win-Setup.exe, or the portable zip) and the Android app use MAUI. Application id is com.bluegrassiot.mqttprobe.

Platform Data root
Windows %LOCALAPPDATA%\Bluegrass IoT\com.bluegrassiot.mqttprobe\Data
Android /data/user/0/com.bluegrassiot.mqttprobe/files (app-private; not browsable without root or adb)

Under that root:

Item Path
Settings config/appsettings.json
Certificates certificates/cert-{id}.bin
Plugins plugins/

Windows example (settings file):

%LOCALAPPDATA%\Bluegrass IoT\com.bluegrassiot.mqttprobe\Data\config\appsettings.json

Older Windows builds used %LOCALAPPDATA%\User Name\com.bluegrassiot.mqttprobe\Data\config. On first run of a current build, MQTTProbe copies that folder into the Bluegrass IoT path if the new location is empty, and leaves the old folder as a backup.

How secrets are protected

Desktop (Linux and macOS Photino)

Secrets are encrypted with AES-256-GCM on disk. The master key is protected by the OS when possible:

  • macOS: Keychain
  • Linux: libsecret (GNOME Keyring or equivalent)
  • Windows Photino (if used): current-user DPAPI

If no OS keyring is available, a raw .key file is used as a fallback. That is weaker: it relies on filesystem permissions (mode 600 on Unix). The app shows a warning banner when this mode is active.

Windows and Android apps (MAUI)

Secrets use the platform native secure storage:

  • Windows: PasswordVault
  • Android: Android Keystore

Web and Docker

Secrets are protected by ASP.NET Data Protection and stored in config/secrets.dat. Data Protection keys live in config/dp-keys/.

On Linux or in Docker, set the MQTTPROBE_KEK environment variable to a base64-encoded 32-byte AES key to protect the Data Protection key ring:

export MQTTPROBE_KEK=$(openssl rand -base64 32)

On Windows, the key ring uses DPAPI.

Keep secrets.dat and dp-keys/ on the same volume. If either is lost, the other becomes useless.

Client certificates

Client certificates are encrypted at rest with AES-256-GCM. The encryption key and stored PFX password (the "envelope") are kept in the platform secret store, separate from the certificate blob.

Supported formats: PFX/P12 and PEM with a separate private key file.

On the Web host, the certificate and its password are uploaded to the MQTTProbe server. The server operator is in the trust boundary.

On desktop and mobile, the key stays on the device.

For the import UI steps, see Connection Setup: Client Certificate.

Backups and recovery

Docker: Back up the mqttprobe-config volume (contains appsettings.json, secrets.dat, dp-keys/, and certificate blobs). Without dp-keys/ the encrypted secrets are useless.

docker compose cp mqttprobe:/app/config ./backup

Desktop: Back up the entire config root. You also need the OS keyring (or the raw .key file if keyring is unavailable) to decrypt secrets on a new machine. Without the master key, ciphertext is unrecoverable.

What you lose if the key is gone: Broker passwords and client certificate encryption keys. You will need to re-enter passwords and re-import certificates.

Never copy secrets to temp directories or commit them to source control.

Related

Clone this wiki locally