How to Use Custom Encryption Keys
This page applies to multiple products published by Synametrics Technologies, Inc., which includes:
Syncrify,
SynaMan, and
SyncriTab.
For simplicity, we are only using Syncrify in this article. The instructions you see on this page will work with
SynaMan and SyncriTab as well.
Why a Custom Encryption Key Matters
Syncrify stores several pieces of sensitive information on disk, including credentials. By default these
values are protected with a built‑in encryption key that ships inside the product. Because that key is
the same in every copy of Syncrify, anyone who obtains both the software and your configuration files could,
in theory, decrypt those secrets.
A
custom encryption key replaces that shared key with one that is unique to your installation and
known only to you. Once configured, even if someone gets hold of your configuration files they cannot
decrypt the secrets without your key.
Keep a Backup
Store a secure copy of your key or passphrase.
If it is lost, data encrypted with it
cannot be recovered.
How It Works
- You supply a passphrase through an environment variable or a file. Syncrify derives an AES key
from it.
- New secrets are encrypted with your key.
- The passphrase itself is never written into the Syncrify configuration. Syncrify keeps only a
reference to your chosen source, so the secret stays under your control.
- You may supply a passphrase of any length.
Two ways to provide the key. An environment variable (recommended) keeps the secret out
of the file system entirely. A file is also supported, provided you restrict its permissions so
that only the account running Syncrify can read it. Both are described below.
Environment Variable
Set an environment variable named
SYNAMETRICS_CUSTOM_KEY_PASSPHRASE to your passphrase. This environment variable
must be visible to the account (service) that runs
Syncrify, and Syncrify must be restarted after it is created.
On Windows
Syncrify normally runs as a Windows service. Environment variables must therefore be created at the
system (machine) level, not just for your interactive login.
Option A — Graphical:
- Open Start → search for Edit the system environment variables.
- Click Environment Variables…
- Under System variables, click New…
- Variable name:
SYNAMETRICS_CUSTOM_KEY_PASSPHRASE
- Variable value: your passphrase
- Click OK on each dialog.
Option B — Command line (run the Command Prompt
as Administrator):
setx SYNAMETRICS_CUSTOM_KEY_PASSPHRASE "your-secret-passphrase" /M
The
/M switch writes the variable at the machine level so a service can read it.
Finally, restart Syncrify so the service picks up the new variable:
- Open services.msc, locate the Syncrify service, and choose Restart, or
- run
net stop Syncrify followed by net start Syncrify from an elevated prompt.
A running service does not see a variable created after it started. If a simple service restart does
not work, reboot the machine so the service inherits the new system environment.
On Linux
How you set the variable depends on how Syncrify is started. Most modern installations use
systemd.
Option A — systemd unit file: edit the Syncrify service unit (for example
/etc/systemd/system/Syncrify.service) and add an
Environment line inside the
[Service] section:
[Service]
Environment="SYNAMETRICS_CUSTOM_KEY_PASSPHRASE=your-secret-passphrase"
Option B — systemd EnvironmentFile (keeps the secret out of the unit file). Create a file such
as
/etc/Syncrify/Syncrify.env containing:
SYNAMETRICS_CUSTOM_KEY_PASSPHRASE=your-secret-passphrase
secure it so only root can read it:
sudo chown root:root /etc/Syncrify/Syncrify.env
sudo chmod 600 /etc/Syncrify/Syncrify.env
and reference it from the unit file:
[Service]
EnvironmentFile=/etc/Syncrify/Syncrify.env
Then reload systemd and restart Syncrify:
sudo systemctl daemon-reload
sudo systemctl restart Syncrify
Option C — init / startup script: if Syncrify is launched from a shell script, add an export line
near the top of that script, before Syncrify is started:
export SYNAMETRICS_CUSTOM_KEY_PASSPHRASE="your-secret-passphrase"
then restart the service or the machine.
