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