What are the artifactory.key & master.key and what are they used for?

Ariel Kabov
2019-08-11 06:36

Relevant Versions: Artifactory 6. 
The information mentioned in this article is not relevant for previous Artifactory versions.

Located at $ARTIFACTORY_HOME/etc/security, we have 2 important .key files.
This article is to describe what they are used for, and their importance.

General recommendation: Always back up both of the keys in order to ensure an easy roll-back strategy in case of an emergency. 

The artifactory.key

The artifactory.key is a 128-Bit AES encryption key.
Prior to Artifactory 5.9, the encryption was PBEwithSHA1AndDESede.

The artifactory.key is being used to encrypt all passwords that are saved in the Global Configuration Descriptor. This includes configured passwords of remote repositories, replication servers, LDAP servers, etc.
Encrypted data will start with the string ‘AM’.

Example of an artifactory.key using 128-Bit AES encryption:JS.2whsQ.AES128.93Mqdo3D2AeHxdK2T3AujrbSh

Example of an artifactory.key using outdated PBEwithSHA1AndDESede encryption:JR2YxGPoiQWMe5LjB88jM6zCPHBf5zHCsebJyWwzaWCr1UH7XRipnT5LLPhNgrTSuvwVVVHxwUam3cX5AcrUj2XnY4WgV6qjUKNg8xoo5nbq5NPEgzAUme2sbqCYB74ugHuke6JidWYMBQqYdgd7tuQyrAdfQzrCwzS1PMYxUYeEneLv2WPYZK5V6MFCwgv5REcfzWeAaFvuJ9kAJLACxwvwWfD9utXbNtQoDqmiDVeptv9zZC7TZMXveRfBujCCEUATUm8AKe3y5cLrTWZUeuCut8VuPHGU3AatvU5EUeMKbRGDpDNyRQ6NQBgUwbASGq5ytoBCqv4j7RKM3CtheSB1bGN6a5wdH9JrLZDoBAXM63Mav6cZyDAwz6p2g8MkoRbF38DmwqwSx2cNUmLcHPa5gen1eqrVcePyY49Qy6p7pduXgJhWzfCAWMug8RnxPirFLuJ1RnHEiVtTcPZxtVDi5wa

There wasn’t an automatic migration to the new encryption, therefore if your system was upgraded from a version below 5.9 and still uses the PBEwithSHA1AndDESede encryption, you can move to the new 128-Bit AES encryption by using the Deactivate Artifactory Key Encryption REST API endpoint, and then re-enable it using the Activate Artifactory Key Encryption REST API

Note: In the case of data corruption, the “Deactivate Artifactory Key Encryption” REST API may fail, and leave your system in an unhealthy state. Our recommendation will be to test the deactivation procedure first in a staging environment.

In case the artifactory.key is lost, the only way to recover is to override all encrypted data in the Configuration Descriptor with plain text.

The master.key

The master.key is an AES 128-Bit secret key, introduced in Artifactory 5.7.
By default the master.key file is automatically generated during the initial start-up of Artifactory. Optionally, you can generate one manually by running ‘openssl rand -hex 16’, which will output a 128-Bit key size (hexadecimal encoded). Place this key as $ARTIFACTORY_HOME/etc/security/master.key before starting Artifactory the first time.

Here is an example of a master.key file:2672b66f91e12ff207d77cd34d94d997

One of the main usages of the master.key, is being a critical requirement when setting up a High Availability cluster of Artifactory. Without the master.key, you won’t be able to connect a node to an HA cluster. 
The master.key is also being used to encrypt all configuration files that are saved in the DB (and synchronized between HA nodes), in addition to passwords saved on the filesystem ($ARTIFACTORY_HOME/etc/db.properties, as an example).
Moreover, all sensitive data managed by Access is also encrypted using the master.key, such as users’ encrypted passwords, API keys, etc.
Encrypted data will start with the string ‘JE’.

In case the master.key is lost, there is a procedure you can follow, which will delete it from the Artifactory DB, and will delete all of the data that is encrypted using it.