Rotating Active IPsec Certificates

Note: Pivotal Platform is now part of VMware Tanzu. In v1.9 and later, Pivotal IPsec is named IPsec for VMware Tanzu.

Page last updated:

This topic describes the process VMware recommends to increase deployment security by rotating certificates in the IPsec for VMware Tanzu manifest.

Why You Need to Rotate Credentials

These are common reasons for rotating credentials:

  • Your organizational security policy may specify how often you should apply these changes.

  • Your certificates are going to expire. To find the expiration dates on your certificates, see Checking Certificate Dates.

About the Procedures

There are two procedures for certificate rotation described in this topic:

  • Procedure 1 describes rotating the following certificates specified in your IPsec manifest:

    • The instance certificate and instance private key
      This procedure requires updating BOSH. It does not include rotating the certificate authority (CA) certificate.
  • Procedure 2 describes rotating your CA certificate in addition to your instance certificate and instance private key. This procedure requires updating BOSH three times.

Note: The rolling deploys during these procedures result in minimal deployment downtime.

Procedure 1: Rotate the Instance Certificate and Instance Private Key

Follow the steps below to rotate the instance certificate and instance private key.

  1. Generate and sign a new instance certificate using your existing IPsec CA certificate.

  2. Update the instance certificate and the private key fields in your ipsec-addon.yml file with new values from the previous step.

  3. Update the runtime config by running the following command:

    bosh -e BOSH-ENVIRONMENT update-runtime-config --name=ipsec PATH-TO-SAVE-THE-RUNTIME-CONFIG
    

    Note: This step results in a few minutes of app downtime.

  4. Navigate to your interface in a browser.

  5. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  6. Click Apply Changes.

Procedure 2: Rotate the CA Certificate, the Instance Certificate, and Instance Private Key

Follow these steps to rotate the CA certificate, instance certificate, and instance private key.

  1. Generate a new CA certificate.

  2. Append the newly generated CA certificate under the existing certificate as a new yaml list element in your ipsec-addon.yml. For example:

    ca_certificates:
      - |
         -----BEGIN CERTIFICATE-----
         ... <ORIGINAL ROOT>
         -----END CERTIFICATE-----
      - |
         -----BEGIN CERTIFICATE-----
         ... <NEW ROOT>
         -----END CERTIFICATE-----
         .
         .
         .
    

    For v1.8.12 and above: IPsec supports CA certificate chain.

    Concatenate the contents of the root and the intermediate certificates as one of the list items in ca_certificates (the root CA is at the top).

    ca_certificates:
      - |
         -----BEGIN CERTIFICATE-----
         ... <ORIGINAL ROOT>
         -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ... <ORIGINAL INTERMEDIATE 1 ISSUED BY THE ORIGINAL ROOT CERT ABOVE>
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ... <ORIGINAL INTERMEDIATE 2 ISSUED BY THE ORIGINAL INTERMEDIATE 1 ABOVE
        ... AND SIGNS THE OLD INSTANCE CERT>
        -----END CERTIFICATE-----
      - |
        -----BEGIN CERTIFICATE-----
        ... <NEW ROOT>
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ... <INTERMEDIATE 1 ISSUED BY THE NEW ROOT CERT ABOVE>
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ... <INTERMEDIATE 2 ISSUED BY THE NEW INTERMEDIATE 1 ABOVE
        ... AND SIGNS THE NEW INSTANCE CERT>
        -----END CERTIFICATE-----
    

    Note: The root and the intermediate certificates cannot have the same subjectName, also called the common name and set with CN=.
    Also, the root certificate must be the first certificate of the chain.

  3. Update the runtime config by running the following command:

    bosh -e BOSH-ENVIRONMENT update-runtime-config --name=ipsec PATH-TO-SAVE-THE-RUNTIME-CONFIG
    

    Note: This step results in a few minutes of app downtime.

  4. Navigate to your Ops Manager interface in a browser.

  5. If you are using Ops Manager v2.3 or later, click Review Pending Changes. For more information about this Ops Manager page, see Reviewing Pending Product Changes.

  6. Click Apply Changes.

  7. Generate and sign a new instance certificate using your new CA certificate.

  8. Update the instance certificate and the private key fields in the your ipsec-addon.yml file with new values from above.

  9. Repeat step 3 to update the runtime config.

  10. Navigate to your Ops Manager interface in a browser.

  11. If you are using Ops Manager v2.3 or later, click Review Pending Changes.

  12. Click Apply Changes.

  13. Delete the older CA certificate in the ipsec-addon.yml file.

  14. Repeat step 3 to update the runtime config.

  15. Navigate to your Ops Manager interface in a browser.

  16. If you are using Ops Manager v2.3 or later, click Review Pending Changes.

  17. Click Apply Changes.