Skip to content

Encrypting the Configuration

Encrypt the MetaMiner Server configuration file with a password, so that MMA asks for that password at every start.

How it works

The server configuration lives in server\config\config.json. Passwords inside it are always stored encrypted. Encrypt Config encrypts the whole file as well:

File Purpose
config\config.ecf The encrypted configuration. MetaMiner reads it instead of config.json
config\config.ek Key file that lets the MetaMiner Server service start without anyone typing the password
MetaMinerServer.properties Gets the entry use.encrypted.config=true

From then on, the MetaMiner Administrator (MMA) asks for the configuration password each time it starts. The MetaMiner Server service starts unattended as before.

Treat encryption as one layer. Keep NTFS permissions on server\config limited to administrators and the MetaMiner service account.

Before you begin

  • Run MMA on the MetaMiner Server host as a Windows administrator.
  • Back up the server\config folder and MetaMinerServer.properties.
  • Choose a password and store it in your password vault. If the password is lost, the configuration cannot be opened in MMA and you must configure MetaMiner again.

Steps

  1. In MMA, open the Security menu and click Encrypt Config.... The item is shown only while the configuration is not encrypted.

  2. In Encrypt Config, enter the password and confirm it.

    Image of the Encrypt Config password dialog with the warning about losing the password

    ../images/security/mma-encrypt-config.png

  3. MMA shows Config was successfully encrypted!.

  4. Close MMA and restart the MetaMiner Server service.
  5. Move the earlier plain-text config\config.json and its backup copies (config.json.back_*) to protected storage, or delete them once you have confirmed step 6.
  6. Start MMA. It shows Config is Encrypted and asks for the password.

TODO: confirm step 5

Confirm that MetaMiner no longer reads config.json or writes plain-text backups once use.encrypted.config=true, so customers can safely remove them.

Start MMA with an encrypted configuration

  1. Start MMA. The password prompt appears.
  2. Enter the configuration password and click OK. Click Exit to close MMA without changes.

Do not click Cancel unless you want to start over

Cancel asks Are you sure to erase current config?. If you confirm, MMA erases the current configuration and encrypts a new, empty one with a new password. Click Cancel only to rebuild the configuration from scratch.

If you see Incorrect password or decryption failure, check the password and try again.

What changes with an encrypted configuration

  • MMA writes the configuration file directly instead of sending changes to the running MetaMiner Server. Restart the MetaMiner Server after you change settings.
  • Some environment settings cannot be edited while the MetaMiner Server is running. Stop the server, edit, then start it.

Verify

  1. server\config\config.ecf and server\config\config.ek exist.
  2. MetaMinerServer.properties contains use.encrypted.config=true.
  3. MMA asks for the password at start, and the MetaMiner Server starts without it.

Troubleshooting

MMA starts without asking for a password

MMA was not started from its shortcut, so it did not read MetaMinerServer.properties. Start MMA from the MetaMiner Administrator shortcut or MetaMinerAdmin.exe in the server folder.

Encrypt Config... is missing from the Security menu

The configuration is already encrypted.

TODO: document how to turn encryption off

MMA has no menu item to decrypt the configuration in this release. Product team to confirm the supported procedure.

Next steps