Skip to main content

Re-encryption in Nexus Repository

Nexus Repository uses a static key for reversible encryption to store sensitive data. Secrets refer to sensitive configuration values such as API keys, SAML passwords, and other credentials. We recommend administrators change their encryption key used for secrets from the default value to enhance their repository security.

FIPS 140-3 Compliance

For FIPS compliance, all key-passwords used must have at least 112-bit complexity. These must also use a more secure encryption algorithms which will need to be updated. Secrets are complemented by an API key, which is encrypted with the same mechanism. By default, secrets use a password and salt that are not FIPS compliant, so configuring fixed encryption is required.

See FIPS 140-3 Compliance documentation for details.

Re-encryption Health Check

The following health check warning displays when the default encryption key has not been updated. Use this guide to re-encrypt your secrets to resolve the warning.

Nexus was not configured with an encryption key and is using the Default key

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.

Changing the Encryption

When you already have an encryption configuration file with a fixed encryption and need to update the keys, you must also provide the previous encryption details under the previousFixedEncryption section. Ensure your existing configuration uses secure parameters as defined by FIPS.

Steps for Re-Encryption

  1. Deploying in High Availability (HA) Environments (optional)

    Deploying to HA environments require that the key used for encryption is available to all nodes before the re-encryption process is triggered.

    Review the High Availability (HA) Deployments section below

  2. Create a JSON File Containing Your Custom Encryption Key

    For improved security and to simplify deployment of your custom encryption keys, they are stored in a external json file which is referenced by your runtime configuration.

    See Create a JSON for Custom Encryption Key

  3. Add the Secrets File to the Nexus Repository Configuration

    The Nexus Repository runtime must include the secrets file during the initial startup. The active key configured in the secrets file is when re-encrypting secrets.

    See Use a Secrets File to the Nexus Repository Configuration

  4. Set the Active Encryption Key API

    Use the API to trigger Nexus Repository to re-encrypt secrets using a new encryption key stored in your secrets file.

    See the Set the Active Encryption Key API section below

Set the Active Encryption Key API

Use the following API call to trigger a task to re-encrypt existing secrets using your custom encryption key.

PUT /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.

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"
}'

Warning

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

In a HA cluster all Nexus Repository nodes require access to the secrets found in the JSON file

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.

    All 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. Restart the cluster to use the new key without requiring the API call.