Re-encryption in Nexus Repository
Nexus Repository uses a static key for reversible encryption to store sensitive data like passwords. We recommend administrators change the encryption key to enhance their repository security.
Best Practice When Upgrading
The Nexus Repository upgrade involves applying database scripts to change the schema which the re-encryption mechanism depends on. We recommend avoiding making changes to the encryption while performing an upgrade.
Perform the re-encryption outside of your regular upgrade maintenance plan.
The following health check warning displays when the default encryption key has not been updated:
Nexus was not configured with an encryption key and is using the Default key
Use the sections below to re-encrypt your secrets to resolve the warning.
Create a JSON File Containing Your Custom Encryption Key
Create a JSON file containing your custom encryption key. This file remains part of your deployment to decrypt persisted secrets.
Use the following JSON format and save it as a .json
file in a secured location.
{ "active": "my-key", "keys": [ { "id": "my-key", "key": "some-secret-key" } ] }
The JSON file specifies the following properties:
active
- The key to use for encryption; the value matches theid
in thekeys
arraykeys
- An array containing key objectsid
- A unique identifier for the keykey
- The secret key value; any random string value. Usenull
in HA environments for the first restart as described in the section below
Add the Secrets File to the Nexus Repository Configuration
Use one of the following methods to configure Nexus Repository with the custom encryption key.
Set in the Secrets File Property in nexus.properties
Add the
nexus.secrets.file
property pointing to the secrets JSON file in your$data-dir/sonatype-work/nexus3/etc/nexus.properties
.nexus.secrets.file=/full/path/to/your/secrets/<name_of_key_file>.json
Set the Secrets File as an Environment Variable
Use the
NEXUS_SECRETS_KEY_FILE
environment variable to pass your JSON key file to the Nexus Repository.export NEXUS_SECRETS_KEY_FILE=/opt/nexus/keys/<name_of_key_file>.json
Configuring in Helm Charts
Helm chart set the
secret.nexusSecret.secretKeyfile
parameter found in the Helm chart repository README.Using AWS Secrets Manager or Azure Key Vault
Those using AWS Secrets Manager or Azure Key Vault need to include the secret in AWS Secrets Manager/Azure Key Vault. See the Helm chart repository README for details.
Set the Active Encryption Key
Use the following API call to trigger a task to re-encrypt existing secrets using your custom encryption key.
/service/rest/v1/secrets/encryption/re-encrypt
The request body includes the following parameters:
secretKeyId
- The ID of the new encryption key as it appears in the secrets file.notifyEmail
(Optional) - An email address to receive a notification about the task result (requires email service configuration).
A successful request schedules a re-encryption task with the task ID in the response body.
Example Request
curl -u "admin" -X 'PUT' \ 'https://<your-instance-url>/service/rest/v1/secrets/encryption/re-encrypt' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "secretKeyId": "string", "notifyEmail": "string" }'
Interrupting the re-encryption task may leave secrets encrypted with the old key. Fix this by resending the API call and allowing the task to complete.
High Availability (HA) Deployments
When using rolling restarts in an HA cluster, temporarily set the active
key to null
for the first restart. This is necessary as the nodes do not have access to the new key until they are restarted. The secrets file must be accessible by the nodes or the re-encryption task fails.
This allows the nodes to come up with the new secrets file without attempting to use an inactive key. Once all nodes are up, activate the new key using the API, and update your secrets file to reflect this change for subsequent restarts.
Deploy the secrets file
Create a JSON file containing your custom encryption key. For the first restart, set the "active" key to null as the nodes initially won't have access to the new key. The Nexus Repository nodes require access to the JSON file.
Rolling restart
Perform a rolling restart of your Nexus Repository instances. This means restarting each node one by one, allowing the others to continue running and maintain service availability.
Activate the new key
Once all nodes have restarted and are running with the new secrets file, you need to activate the new encryption key using the REST API endpoint. Provide the
secretKeyId
that matches the id in your secrets file.Update the secrets file
After successfully re-encrypting, update your secrets file and set the "active" key to your
secretKeyId
. Future restarts will use the new key without requiring the API call.