Re-encryption in Nexus Repository

Sonatype Nexus Repository employs reversible encryption to store sensitive data like passwords for certain features. By default, Nexus Repository uses a static key for this encryption. However, administrators have the flexibility to configure and change this key, enhancing security.

Health Check Warning

If you have not configured and run re-encryption and are still using the default key, you will see a health check warning with the message "Nexus was not configured with an encryption key and is using the Default key" after upgrading to 3.73.0+. Follow the steps in this topic to resolve the warning.

Re-encryption involves a few steps:

Create the new JSON key file.
Enable re-encryption through a system property or environment variable; Helm chart, Azure KeyVault, and AWS Secrets Manager users will need to follow additional instructions in the HA README.
Create the re-encryption task via API.

The sections below go through these steps.

Create the JSON Key File

Before using any of the below methods for specifying your key file, you will need to create a JSON file specifying your key. You will need to keep this file permanently in order for Nexus Repository to be able to decrypt persisted secrets. Create the JSON key file using the following format:

{
  "active": "my-key",
  "keys": [
    {
      "id": "my-key",
      "key": "some-secret-key"
    }
  ]
}

The JSON file specifies the following information:

active - Identifies the key currently used for encryption; the value of this field must match the id value of one of the keys defined in the keys array
keys - An array containing key objects
- id - A unique identifier for the key; the value of this field should match the value of the active field if this key is currently in use
- key - The actual secret key value; this can be any random string value

Nexus Repository reads this file during startup, and the active key is used for all new encrypted passwords. You will need to keep this file permanently in order for Nexus Repository to be able to decrypt persisted secrets.

Note for High Availability (HA) Deployments

When configuring the secrets file for the first time in an HA cluster using rolling restarts, set the active key to null. This is necessary because nodes that haven't been restarted won't have access to the new keys yet. Use the REST API to switch the active key after all nodes have been restarted.

You can now proceed to one of the below methods for enabling re-encryption.

Enable Re-Encryption

After creating the JSON key file, follow one of the below methods for providing that file to Nexus Repository.

Enable Re-Encryption through Secrets File Property

Locate and open your $data-dir/sonatype-work/nexus3/etc/nexus.properties file.

Add the nexus.secrets.file property and set it to point to the full path to your secrets JSON file as in the following example:

nexus.secrets.file=/full/path/to/your/secrets/file.json

Enable Re-Encryption through Secrets File Environment Variable

To use the NEXUS_SECRETS_KEY_FILE environment variable, pass your JSON key file to Nexus Repository using a command like the following:

export NEXUS_SECRETS_KEY_FILE=/opt/nexus/keys/<name_of_key_file>.json

Enable Re-Encryption for Helm Chart Users

Helm chart users should use the secret.nexusSecret.secretKeyfile parameter detailed in the Helm chart repository README.

Enable Re-Encryption for AWS Secrets Manager or Azure Key Vault Users

Those using AWS Secrets Manager or Azure Key Vault will need to create a secret in AWS Secrets Manager/Azure Key Vault; more details are included in the HA README.

Create Re-encryption Task via API

The re-encryption process allows you to switch to a new encryption key, ensuring that existing secrets are re-encrypted with the new key.

Considerations Before Starting Re-encryption

Interrupting the re-encryption task that you will trigger during this process or shutting down a node mid-process might leave some secrets encrypted with the old key. Nexus Repository can still decrypt these, but you will need to re-trigger the re-encryption process to ensure complete security.
In cluster mode, the secrets file must be present and accessible on all nodes. Each node must also have access to the new key; otherwise, the task will fail.

curl -X 'PUT' \
  'https://<your-instance-url>/service/rest/v1/secrets/encryption/re-encrypt' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'NX-ANTI-CSRF-TOKEN: <your-token>' \
  -H 'X-Nexus-UI: true' \
  -d '{
  "secretKeyId": "string",
  "notifyEmail": "string"
}'

Update the secrets file to specify the new active key.
Ensure all Nexus Repository nodes have access to the updated secrets file.
Trigger re-encryption by using the /service/rest/v1/secrets/encryption/re-encrypt API endpoint. The request body should include the following:
1. secretKeyId - The new encryption key's ID as it appears in the secrets file.
2. notifyEmail (Optional) - An email address to receive a notification about the task result (requires email service configuration).
A successful request will schedule a re-encryption task; the task ID is returned in the response body.