Certificate Rotation

This page describes the rotation of certificates for the standalone components, such as the a9s Backup Manager or the a9s SPIs, as well as the components that are colocated on a Service Instance like the a9s Backup Agent.

It may be necessary to rotate either only the leaf certificates themselves or the CA certificate as well. Depending on the use case, further steps are required. These are explained in the following sections.

Leaf Certificate Rotation

Service Instance's Colocated Components

The leaf certificates of components that are colocated on an individual Service Instance can be rotated by using the custom parameter force_certificate_rotation:

cf update-service <service_instance_name> -c '{"force_certificate_rotation": true}'

Standalone Components

To rotate a leaf certificate of a standalone component, CredHub must be used to regenerate the related certificate:

credhub regenerate -n '<path-to-certificate>'

And apply the new leaf certificate with bosh deploy:

bosh -d <deployment-name> deploy (...)

CA Certificate Rotation

For the CA certificates rotation, the rotation steps provided by CredHub are used. For more information, see CredHub Rotation documentation.

Prerequisites

CredHub MUST have the credhub.certificates.concatenate_cas configuration set to true.

danger

Always rotate the CA and the related certificate(s) before they expire, as rotating an expired CA, or related certificate, will lead to a failure and your a9s Data Service will be in a broken state.

This means that every step described in this section must take place, in order to ensure that such failure does not occur.

Step 1: Regenerate the Root CA

First, retrieve the id of the CA certificate (/a9s_private_components_ca):

credhub curl -p "/api/v1/certificates?name=/a9s_private_components_ca"

Example output

{
  "certificates": [
    {
      "id": "8f8cbee2-af90-4afb-9f57-e934e2cb4dcf",
      "name": "/a9s_private_components_ca",
      "signed_by": "/a9s_private_components_ca",
      (...)

Then, use the id to regenerate the CA certificate:

credhub curl -p "/api/v1/certificates/8f8cbee2-af90-4afb-9f57-e934e2cb4dcf/regenerate" \
  -d '{"set_as_transitional": true}' -X POST

After this step, the old CA and the new CA have been concatenated.

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. Colocated components must be updated using the a9s Deployment Updater of the corresponding a9s Data Service. For this, the strategy.update.instance_type property of the a9s Deployment Updater MUST be set to provisioned.

Step 2: Regenerate Leaf Certificates with the New CA Certificate

First, retrieve the CAs and identify the id for each certificate version:

credhub curl -p "/api/v1/data?name=/a9s_private_components_ca&current=true"

Example output

{
  "data": [
    {
      "certificate_authority": true,
      "expiry_date": "2024-02-22T22:18:58Z",
      "generated": true,
      "id": "ac1b5129-4865-4473-84e9-902afee18921",
      "metadata": null,
      "name": "/a9s_private_components_ca",
      "self_signed": true,
      "transitional": false,
      "type": "certificate",
      (...)
    },
    {
      "certificate_authority": true,
      "expiry_date": "2024-02-23T03:22:31Z",
      "generated": true,
      "id": "90cfe1cc-9f51-4824-a775-0f22d53d5a20",
      "metadata": null,
      "name": "/a9s_private_components_ca",
      "self_signed": true,
      "transitional": true,
      "type": "certificate",
      (...)

Identify the certificate version with the transitional flag set to false, and switch the transitional flag:

credhub curl -p /api/v1/certificates/8f8cbee2-af90-4afb-9f57-e934e2cb4dcf/update_transitional_version \
  -d '{ "version": "ac1b5129-4865-4473-84e9-902afee18921" }' -X PUT

Then, regenerate all leaf certificates signed by the CA on /a9s_private_components_ca. The new certificates will be generated and signed with the new CA certificate.

credhub bulk-regenerate --signed-by=/a9s_private_components_ca

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. Colocated components must be updated using the a9s Deployment Updater of the corresponding a9s Data Service. For this, the strategy.update.instance_type property of the a9s Deployment Updater MUST be set to provisioned.

Step 3: Remove the Old CA Certificate

First, remove the old CA certificate from CredHub:

credhub curl -p /api/v1/certificates/8f8cbee2-af90-4afb-9f57-e934e2cb4dcf/update_transitional_version \
  -d '{"version": null}' -X PUT

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. Colocated components must be updated using the a9s Deployment Updater of the corresponding a9s Data Service. For this, the strategy.update.instance_type property of the a9s Deployment Updater MUST be set to provisioned.

After that, the old CA certificate should have been removed, and there only be the new CA certificate and the new leaf certificates signed by the new CA.