Each Base Monitor uses encryption to protected various secrets stored in the SQL Monitor database, including credential passwords and API secret keys for monitored servers. By default, the encryption keys are stored in a file found at %ProgramData%\Red Gate\SQL Monitor\Secrets\keys.txt. If this file does not exist, it will be automatically created when the Base Monitor first starts.

Protecting the encryption keys file

It is strongly recommended that you take the following steps to protect the encryption keys file.

Restrict access to the encryption keys file

Restrict access to the encryption keys file so that unauthorized users can't view the file's contents. Ideally access should be limited to just the Windows service account that the Base Monitor service runs under, as well as any other accounts necessary for any automated backup process you may have in place.

Backup the encryption keys file

Make a backup copy of the encryption keys file to avoid losing access to any of the encrypted passwords in the SQL Monitor database in the event of unexpected loss of access to the encryption keys file. Avoid storing the encryption keys backup alongside backups of the SQL Monitor database, since access to both will enable the secrets in the database to be decrypted.

Changing the location of the encryption keys file

The default location of the encryption keys file can be overridden by creating a keyStore section with a path property to the application settings file found at %ProgramData%\Red Gate\SQL Monitor\appsettings.json like this example.

{
    "keyStore": {
        "path": "C:\\AlternateKeyStorePath\\keys.txt"
    }
}

Please note how a json file requires each backslash ('\') character in the path to be escaped using a double-backslash ('\\').

After making changes to the file, you must restart the Base Monitor service for the changes to take effect.

Encryption keys file contents and how they are used

When initially created, the contents of the encryption keys file looks something like this:

# This file contains one or more encryption keys used to protect credentials held by SQL Monitor.
#
# More information about this file can be found at https://www.red-gate.com/sm/encryption-key-store
# which we strongly recommend you read.

aBWVrVPGtBzUmIHTuuISGLy6ePCicotWoGAthgrd9wA=  # Created on 2023-03-06 12:01:16Z

However, the file can support multiple keys, like this:

# This file contains one or more encryption keys used to protect credentials held by SQL Monitor.
#
# More information about this file can be found at https://www.red-gate.com/sm/encryption-key-store
# which we strongly recommend you read.

s+d6uMYJ5K826Yi2FdgQLfLCfDm0Bs+xJlw59LuH/10=  # <-- This is the Credential Encrypting Key.
1c9YHoH6nPD3JnjnfyHBZVuCE2x1M6WUd4j4BPfG98Y=
sVFUbd4Svl/dML4/pTxNBS5qcvUlMaaS+CG8JQox1BI=
aBWVrVPGtBzUmIHTuuISGLy6ePCicotWoGAthgrd9wA=  # Created on 2023-03-06 12:01:16Z

All keys in the file may be used to decrypt credentials stored in the SQL Monitor database, but the first key in the file is treated differently to all subsequent keys. It's known as the Credential Encrypting Key and is the only key used to encrypt credentials before they're stored in the SQL Monitor database. Furthermore, when the Base Monitor service starts, any credential that is encrypted using one of the other keys is automatically rewritten using the Credential Encrypting Key.

Encryption key rollover

Encryption key rollover should be carried out in accordance with your organisation's security policies. It can be carried out by adding a new Credential Encrypting Key into the encryption keys file and then restarting the Base Monitor service.

Adding a new Credential Encrypting Key

Each encryption key is a random 32 byte sequence that is then base-64 encoded. You can generate a new key using the following command from a PowerShell Core command prompt:

[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

The new key must be inserted into the file before all existing keys, since SQL Monitor treats the first key in the file as the Credential Encrypting Key. You should retain the existing keys in the file so that SQL Monitor can continue to decrypt credentials that have been encrypted with those keys.

Restarting the SQL Monitor base monitor service

Once the encryption keys file has been updated, your must restart the Base Monitor service because it only reads the keys once on start up. When the service restarts, all credentials stored in the SQL Monitor database will be promptly re-encrypted using the new key.

Dealing with multiple Base Monitors

If you have multiple Base Monitors, whether they all have separate encryption keys files or all share the same file, each Base Monitor must be restarted after its corresponding keys file has been updated.

More information

If you have trouble working with encryption keys, see Resolving encryption key issues for more information.