ARTIFACTORY: How to reset the master key

Versions: Artifactory 7.X

It hopefully goes without saying that this file is very important, and it should not be lost. If the master.key is lost, the services that rely on the master.key won't be able to start. That being said, recovery is still possible!

The master.key is a secret key used to encrypt key tables in the database, it was introduced in Artifactory 5.7. By default, this file is automatically generated during the first start of the application.

One of the main usages of the master.key is to be a key step when setting up a High Availability cluster of Artifactory. The master.key is also used to encrypt all sorts of information saved in the database, in addition to passwords saved on the file system (Ex: $JFROG_HOME/etc/system.yaml). Moreover, all sensitive data managed by Access are also encrypted using the master.key, such as users’ passwords, API keys, etc.
 
Recovering from a lost master.key is tricky and requires connecting to the database. It’s a different procedure between Artifactory version 6.x and 7.x.

Note:

In Artifactory 7.71 and up, there was a migration of security configurations (Mainly LDAP) from Artifactory database tables to the Access database tables. This improved security of the platform, but it also had an unfortunate side effect of encrypting the LDAP Manager's Password using the master key as a discrete setting.

As a result, in versions 7.71 and up, you must manually reset the LDAP configuration after recovering Artifactory. Ensure you have a local Admin account to log in with after following the steps here.



7.X Master Key Reset Steps

Reset all Encrypted File Passwords

The database password in the $JFROG_HOME/etc/system.yaml is encrypted by the master key file. Replace this encrypted password in this file with the original, plain text password.

Locate the $JFROG_HOME/etc/artifactory/binarystore.xml file, then identify any terms starting with "JE" or "AM" and remove them. Make sure to replace the removed sections with the original plaintext values.

Before proceeding with the next step, please make a backup your database schema by taking a database dump. After the information is backed up and saved, we next need to delete a series of rows which were encrypted by the lost key.

These rows are either temporary or are encrypted files from the file system, so there shouldn't be any data loss from these steps. That being said, please be careful.



Delete Encrypted Rows from DB Tables:

These queries remove the encrypted rows from the database, they start with "JE" (Short for "JFrog Encryption").

DELETE FROM access_configs WHERE data LIKE 'JE%';

DELETE FROM access_users_custom_data WHERE PROP_VALUE LIKE 'JE%';

DELETE FROM access_master_key_status WHERE status = 'on';

DELETE FROM configs WHERE data LIKE 'JE%';

DELETE FROM master_key_status WHERE status = 'on';

DELETE FROM access_platform_config WHERE config_key LIKE 'jfconnect.entitlements%';

DELETE FROM access_platform_config WHERE config_key LIKE 'ldap.setting%';

DELETE FROM access_platform_config WHERE config_key LIKE 'saml%';



For Artifactory version 7.111.x and above:

Execute the following command in addition to those listed above:

delete from jfconfig_platform_config where config_key like 'jfconnect.entitlements%';



If the embedded JFrog Mission Control has been enabled:

If you see these lines in your Artifactory system.yaml, or know that Mission Control has been enabled in this Artifactory installation, you need to perform an additional delete action as these MC tables, they are also encrypted.

#If you see this in the system.yaml, remove the MC encrypted table rows
mc:
  enabled: true

Proceed to remove the "mc" table rows:

DELETE FROM mc_cluster_info WHERE property_key='master_key_hash';

DELETE FROM mc_token WHERE token_value LIKE 'JE%';



Remove Encrypted Files

Finally, remove the following files from the Artifactory file system. They contain encrypted text too. These are temporary files and they will regenerate as long as they are not present during the next startup.

#These will regenerate on startup
rm $JFROG_HOME/var/etc/artifactory/security/access/access.admin.token
rm $JFROG_HOME/var/etc/security/join.key



Try to start Artifactory

After deleting the above table rows and removing these files, restart the Artifactory instance. It should come online and you can begin the process to recover from the loss of the key.

 
Please note that if you missed one of the above steps, new partially-encrypted data will be regenerated and you'll still get a mismatch error. If your first attempt doesn't work, please try following the whole procedure from the top, a step was probably missed.



Legacy Artifactory 6.X Reset steps:

Change the db.properties password from its encrypted form to clear-text.

Run query: DELETE FROM access_configs WHERE data LIKE 'JE%';

Run query: DELETE FROM configs WHERE data LIKE 'JE%' or data LIKE 'AM%';

Run query: DELETE FROM access_master_key_status WHERE status = 'on';

Run query: DELETE FROM access_users_custom_data WHERE PROP_VALUE LIKE 'JE%';

There may also be a table master_key_status that contains a row similar to access_master_key_status, remove the contents of this table as well

*Optional*: If you are rotating (not resetting) the master.key, remove the master.key from all nodes.

```
Start the nodes.
```