Certificate Rotation

The a9s Data Services Framework leverages CredHub to generate and store the certificates. It provides a set of steps to rotate these certificates. This document describes how to rotate the certificates used to encrypt the communication between the a9s Data Services Framework components. These certificates are generated from the CA stored under /a9s_private_components_ca.

info

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

If you need more information about the rotation steps, please check the CredHub Rotation documentation.

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 should have been concatenated, and they can now be applied with bosh deploy:

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

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

And apply the new certificates with bosh deploy:

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

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

And apply the removal of the old CA certificate to the data service with bosh deploy:

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

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.