Rotating certificate authorities certificates

Managing your public key infrastructure (PKI) with IBM Cloud® Secrets Manager should take into consideration the life-cycle of the CA chain certificates. Those certificates should be periodically rotated and distributed prior to their expiration to maintain uninterrupted TLS workflows for their consumers.

Rotating a root CA

Before you begin

Rotating the root certificate authority is a major change that can impact your entire public-key infrastructure and should be carefully planned ahead of time.

You should plan a time period when both the existing and new root CA certificates overlap to allow the new root CA certificate to be distributed to all consumers.
It is therefore recommended that you set a long validity period for your root CA certificate. In Secrets Manager, the default TTL for root certificates is 10 years.

Rotating your root CA

Notify your PKI users about the upcoming rotation plan. The time when the new root CA will be available for download, the time when new leaf certificates will be issued using the new CA chain, and the time when the existing root CA certificate will expire.
Follow the Creating root certificate authorities process to create a new root CA.
Follow the Creating intermediate certificate authorities process to create your CA chain signed with your new root CA.
Distribute the new root CA to allow all consumers to install it in their trust store alongside the existing root CA.
Monitor your rotation plan and notify your PKI users about each upcoming milestone event.

Rotating an intermediate CA

Before you begin

Notify your PKI users about the upcoming intermediate CA rotation ahead of time.

An intermediate CA can be rotated inline in case it is not in use to sign other intermediate CAs.
In case you have a multi-tier intermediate CA chain, you should create a new intermediate CAs chain alongside the existing one ahead of time and migrate your PKI consumers to use the new chain.

Rotating an intermediate CA inline

An intermediate CA can be rotated inline in case it is an internally signed CA in active state, and it is only used to sign leaf certificates.
Inline intermediate CA rotation will not affect existing leaf certificates that were signed using the previous CA certificate. New leaf certificates will be signed using the new CA certificate.

Rotating using service UI

You can rotate the intermediate CA certificate using the Secrets Manager service UI.

In the console, click the Menu icon > Resource List.
From the list of services, select your Secrets Manager instance.
In the Secrets engines page, click the Private certificates tab.
In the row for the intermediate CA certificate that you want to rotate, click the Details menu .
Click on the Actions button.
Select the Rotate action and confirm.

Rotating using CLI

You can rotate an intermediate CA certificate using the Secrets Manager CLI.

ibmcloud secrets-manager configuration-action-create \                                                               
    --name "your-intermediate-ca-name" \
    --config-action-prototype '{"action_type": "private_cert_configuration_action_rotate_intermediate"}' \
    --config-type private_cert_configuration_intermediate_ca

Rotating using API

You can rotate an intermediate CA certificate using the Secrets Manager API:

curl -X 'POST' \
  --header "accept: application/json" \
  --header "Content-Type: application/json" \
  --header 'X-Sm-Accept-Configuration-Type: private_cert_configuration_intermediate_ca' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{intermediate-configuration-name}/actions" \
  -d '{
      "action_type": "private_cert_configuration_action_rotate_intermediate"
  }'

Replace {instance_ID} and {region} with the values that apply to your Secrets Manager service instance. To find the endpoint URL that is specific to your instance, you can copy it from the Endpoints page in the Secrets Manager UI. For more information, see Viewing your endpoint URLs
Replace {intermediate-configuration-name} with your intermediate configuration name.