Skip to main content

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.

Configuring the Encryption Key

You can specify the encryption key using either the NEXUS_SECRETS_KEY_FILE environment variable or the nexus.secrets.file property. Helm chart users should use the secret.nexusSecret.secretKeyfile parameter detailed in the Helm chart repository README. 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. All methods point to a JSON file with the following structure:

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

The JSON file contains the following information:

  • active - Identifies the key currently used for encryption

  • keys - An array containing key objects

    • id - A unique identifier for the key

    • key - The actual secret key value

Nexus Repository reads this file during startup, and the active key is used for all new encrypted passwords.

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.

Re-encryption Process

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.

  1. Update the secrets file to specify the new active key.

  2. Ensure all Nexus Repository nodes have access to the updated secrets file.

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

  4. A successful request will schedule a re-encryption task; the task ID is returned in the response body.