Skip to main content

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 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 for the first restart as described in the section below

Update the Encryption Algorithm

Users are able to configure a property on nexus.properties file to configure the algorithm used to hash local users passwords.. Consider updating the encryption algorithm to using one-way hashing with PBDKF2 SHA256 or higher.

nexus.security.password.algorithm=PBKDF2WithHmacSHA256

See Local User Password Algorithm

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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.