Skip to main content

Re-encryption in Nexus Repository

Sonatype Nexus Repository uses a static key for reversible encryption to store sensitive data like passwords. Administrators are recommended to 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 multiple changes 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 the id in the keys array

  • keys - An array containing key objects

  • id - A unique identifier for the key

  • key - The secret key value; any random string value. Use null in HA Environments

High Availability (HA) Deployments

When using rolling restarts in an HA cluster, 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 restart. The secrets file must be accessible by the nodes or the re-encryption task fails.

Use the REST API in the final section to set the active key after the nodes restart. Reset the active key to the secret ID for future restarts.

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 -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: <any-token>' \
  -H 'X-Nexus-UI: true' \
  -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.