Encrypting Secrets

Automad stores credentials such as the mail server password, AI provider API keys and the hashes of MCP access tokens as PHP files in the config directory of your installation. This page explains how you can encrypt those secrets with your own key and how to provide that key in different server environments.

Why Encrypt Secrets

The files in the config directory are already protected. They are executed instead of being displayed when they are requested directly, and access to the directory is additionally blocked by server rules. Encryption is an optional, additional layer of protection on top of that. In case such a file ever leaks — for example because a misconfigured server temporarily doesn't execute PHP, a backup ends up in the wrong place or the directory is accidentally committed to a repository — the secrets can't be read without the key.

Encryption is disabled by default and Automad works exactly the same without it. It is enabled automatically as soon as you provide a valid encryption key. There is no setting in the dashboard to turn it on.

What Is Encrypted

Only files that contain secrets are encrypted. The following table lists all files in the config directory and whether they are encrypted once a key is available.

The main configuration stays unencrypted, so that you can still edit it manually. User accounts are not encrypted on purpose, since a lost key would otherwise lock out all users. Note that besides the password hashes, the accounts file also contains the secrets of users that have two-factor authentication enabled in plain text. In case that file leaks, the second factor of those accounts must be considered compromised, while the passwords are still protected by their hashes. Affected users should then change their passwords and set up two-factor authentication again.

Creating a Key

A key must be at least 32 characters long. Shorter keys are ignored and encryption stays disabled. You can generate a good random key using openssl. The following command, run from the Automad base directory, saves a new key to a file next to the document root:

openssl rand -hex 32 > ../automad.key

A hex key only contains letters and digits. It can therefore be used in all kinds of configuration files, such as .htaccess, server configurations or shell scripts, without any quoting. Make sure the key file is readable by the web server.

Providing the Key

The key is passed to Automad using one of two environment variables:

Using a key file is recommended, since only the path to the key is then part of your server configuration. That way the key is not exposed in case the server configuration, for example an .htaccess file, leaks or is committed to a repository. Store the key file outside of the document root whenever possible. Relative paths are resolved against the Automad base directory, which is the directory that contains the index.php file. A path like ../automad.key therefore points to a file next to the document root and keeps working when you move the site together with that file.

How environment variables are defined depends on your web server and hosting environment. The following sections show the most common setups. All examples use a key file, but AM_ENCRYPTION_KEY can be set the same way.

Apache and LiteSpeed

The .htaccess file that ships with Automad already contains a commented example at the top. Uncomment the block and the line of the variable you want to use:

<IfModule mod_env.c>
  SetEnv AM_ENCRYPTION_KEY_FILE "../automad.key"
</IfModule>

Nginx

Add a fastcgi_param to the location block that passes requests to PHP:

fastcgi_param AM_ENCRYPTION_KEY_FILE /var/www/automad.key;

Caddy and FrankenPHP

Use the env subdirective of php_fastcgi when running Caddy with PHP-FPM:

php_fastcgi php:9000 {
  env AM_ENCRYPTION_KEY_FILE /var/www/automad.key
}

With FrankenPHP, the same subdirective is used within php_server:

php_server {
  env AM_ENCRYPTION_KEY_FILE /var/www/automad.key
}

Docker and Hosting Panels

Environment variables that are defined for a container or in the control panel of your hosting provider work as well, as long as they are passed on to PHP. Note that PHP-FPM drops environment variables by default (clear_env = yes). In that case, either set clear_env = no or forward the variable explicitly in the pool configuration:

env[AM_ENCRYPTION_KEY_FILE] = $AM_ENCRYPTION_KEY_FILE

Variables that are passed by the web server, as shown in the sections above, are not affected by clear_env.

Local Development

During development, you can also add the variable to the .env file in the base directory, as described in the environment configuration section:

AM_ENCRYPTION_KEY_FILE=../automad.key

Keep in mind that .env files are only meant for development and must never be deployed to a production server.

Encrypting Existing Files

Once a key is provided, a file is encrypted the next time it is saved, for example when you change the mail settings in the dashboard. All files are also encrypted automatically after the next update of Automad. In order to encrypt all existing files right away, run the migrations manually using the Console:

AM_ENCRYPTION_KEY_FILE=../automad.key php automad/console migrate

Changing or Losing the Key

Encrypted secrets can only be decrypted with the key that was used to encrypt them. When the key is changed or removed, all encrypted settings are treated as not configured and have to be entered again in the dashboard:

There is no other way of rotating a key. Keep this in mind when moving a site to another server and make sure to also move the key file or the variable.

Limitations

Encryption protects secrets in files that leak. It doesn't protect against an attacker who is able to execute code on your server or to read the server's environment, since Automad itself must be able to read the key in order to use the stored credentials.