Managing Non-Configurable TLS/SSL Certificates

This topic describes how to manage Certificate Authority (CA) certificates in your deployment, including how to determine when your CA certificates expire, how to set a custom CA certificate, and how to regenerate and rotate your CA certificates.

For information about rotating IPsec certificates, see Rotating IPsec Certificates.

Planning for Certificate Expiration

Non-configurable CA certificates expire 2 years after creation. Root certificates expire after 4 years. These asynchronous lifecycles make it possible for you to rotate non-configurable certificates without creating and applying a new root certificate.

Depending on the needs of your deployment, there are two approaches to certificate rotation:

Rotating Non-Configurable Certificates

If you need to rotate non-configurable certificates, follow the procedure below. If you need to rotate all your certificates, including creating and applying a new root certificate, follow the procedure in Regenerate and Rotate CA Certificates.

Rotating Expiring Certificates

  1. Use curl to make an API call to regenerate all non-configurable certificates and apply the new CA to your existing Ops Manager Director:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/active/regenerate" \
        -X POST \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
        -H "Content-Type: application/json" \
        -d '{}'
    
    The API returns a successful response:
    HTTP/1.1 200 OK

  2. Navigate to Ops Manager and click Apply Changes. When the deploy finishes, continue to the next section.

Generate and Retrieve Certificates

To manage and retrieve information about certificates in your deployment, use the API calls in this section.

Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN.

Retrieve the Root CA Certificate

To return the Ops Manager root CA certificate as a file, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/download_root_ca_cert \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

To return the Ops Manager root CA certificate as JSON, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/security/root_ca_certificate \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

Retrieve and Generate RSA Certificates

To generate and return a new RSA certificate signed by the root CA, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/certificates/generate \
      -X POST \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

To return metadata from all deployed RSA certificates signed by the root CA, use curl to make the following API call:

$ curl "https://OPS-MAN-FQDN/api/v0/deployed/certificates \
      -X GET \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"

Check Certificate Expiration Dates

The non-configurable certificates in your deployment expire every two years. Use the following procedure to retrieve information about the expiration dates for RSA and CA certificates in your deployment.

  1. Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN.

  2. To check the system for certificates that expire within a given time interval, use curl to make an API call.

    Use the https://OPS-MAN-FQDN/api/v0/deployed/certificates?expires_within=TIME endpoint, replacing TIME with an integer and a letter code. Valid letter codes are d for days, w for weeks, m for months, and y for years.

    For example, run the following command to search for certificates expiring within six months:

    $ curl "https://OPS-MAN-FQDN/api/v0/deployed/certificates?expires_within=6m" \
          -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    Replace YOUR-UAA-ACCESS-TOKEN with the access_token value you recorded in the previous step.

Regenerate and Rotate CA Certificates

Warning: You must complete the procedures in this topic in the exact order specified below. Otherwise, you risk doing damage to your deployment.

Depending on the requirements of your deployment, you may need to rotate your non-configurable CA certificates. Certificates can expire or fall out of currency, or your organization’s security compliance policies may require you to rotate certificates periodically.

You can rotate the certificates in your Pivotal Cloud Foundry (PCF) deployment using curl. PCF provides different API calls with which to manage certificates and CAs. New certificates generated through this process use SHA-256 encryption.

These API calls allow you to create new CAs, apply them, and delete old CAs. The process of activating a new CA and rotating it in gives new certificates to the Ops Manager Director. The BOSH Director then passes the certificates to other components in your PCF deployment.

Note: These procedures require you to return to Ops Manager and click Apply Changes periodically. Clicking Apply Changes redeploys the Ops Manager Director and its tiles. If you apply your changes during each procedure, a successful redeploy verifies that the certificate rotation process is proceeding correctly.

Step 1: Add a New CA

Use the following procedure to add a new CA. You can use a Pivotal-generated CA or provide your own CA using the API calls in this section.

  1. Perform the steps in the Using Ops Manager API topic to target and authenticate with the Ops Manager User Account and Authentication (UAA) server. Record your Ops Manager access token, and use it for YOUR-UAA-ACCESS-TOKEN in the following procedures.

    Note: When you record your Ops Manager access token, make sure you remove any new line characters such as /n. Otherwise the API call in the following step will not succeed.

  2. To use a Pivotal-generated CA, use curl to make the following API call:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/generate" \
      -X POST \ 
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    

    If the command succeeds, the API returns a response that includes the new certificate.
      HTTP/1.1 200 OK
    {
      "guid": "f7bc18f34f2a7a9403c3",
      "issuer": "Pivotal",
      "created_on": "2017-01-19",
      "expires_on": "2021-01-19",
      "active": false,
      "cert_pem": "-----BEGIN EXAMPLE CERTIFICATE-----
        MIIC+zCCAeOgAwIBAgIBADANBgkqhkiG9w0BAQsFADAfMQswCQYDVQQGEwJVUzEQ
        MA4GA1UECgwHUGl2b3RhbDAeFw0xNzAxMTgyMTQyMjVaFw0yMTAxMTkyMTQyMjVa
        MB8xCzAJBgNVBAYTAlVTMRAwDgYDVQQKDAdQaXZvdGFsMIIBIjANBgkqhkiG9w0B
        AQEFAAOCAQ8AMIIBCgKCAQEAyV4OhPIIZTEym9OcdcNVip9Ev0ijPPLo9WPLUMzT
        IrpDx3nG/TgD+DP09mwVXfqwBlJmoj9DqRED1x/6bc0Ki/BAFo/P4MmOKm3QnDCt
        o+4RUvLkQqgA++2HYrNTKWJ5fsXmERs8lK9AXXT7RKXhktyWWU3oNGf7zo0e3YKp
        l07DdIW7h1NwIbNcGT1AurIDsxyOZy1HVzLDPtUR2MxhJmSCLsOw3qUDQjatjXKw
        82RjcrswjG3nv2hvD4/aTOiHuKM3+AGbnmS2MdIOvFOh/7Y79tUp89csK0gs6uOd
        myfdxzDihe4DcKw5CzUTfHKNXgHyeoVOBPcVQTp4lJp1iQIDAQABo0IwQDAdBgNV
        HQ4EFgQUyH4y7VEuImLStXM0CKR8uVqxX/gwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
        HQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQELBQADggEBALmHOPxdyBGnuR0HgR9V4TwJ
        tnKFdFQJGLKVT7am5z6G2Oq5cwACFHWAFfrPG4W9Jm577QtewiY/Rad/PbkY0YSY
        rehLThKdkrfNjxjxI0H2sr7qLBFjJ0wBZHhVmDsO6A9PkfAPu4eJvqRMuL/xGmSQ
        tVkzgYmnCynMNz7FgHyFbd9D9X5YW8fWGSeVBPPikcONdRvjw9aEeAtbGEh8eZCP
        aBQOgsx7b33RuR+CTNqThXY9k8d7/7ba4KVdd4gP8ynFgwvnDQOjcJZ6Go5QY5HA
        R+OgIzs3PFW8pAYcvWrXKR0rE8fL5o9qgTyjmO+5yyyvWIYrKPqqIUIvMCdNr84=
        -----END EXAMPLE CERTIFICATE-----
        "
    

    To provide your own CA, use curl to make the following API call:
    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X POST \ 
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
        -H "Content-Type: application/json" \ 
        -d '{"cert_pem": "-----BEGIN CERTIFICATE-----\EXAMPLE-CERTIFICATE", "private_key_pem": "-----BEGIN EXAMPLE RSA PRIVATE KEY-----\EXAMPLE-KEY"}'
    
    Replace EXAMPLE-CERTIFICATE with your custom CA certificate and EXAMPLE-KEY with your custom RSA key.

  3. Confirm that your new CA has been added by listing all of the root CAs for Ops Manager:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    

    The API call returns the following:
    HTTP/1.1 200 OK
    {
      "certificate_authorities": [
        {
          "guid": "f7bc18f34f2a7a9403c3",
          "issuer": "Pivotal",
          "created_on": "2017-01-09",
          "expires_on": "2021-01-09",
          "active": true,
          "cert_pem": "-----BEGIN CERTIFICATE-----\nMIIC+zCCAeOgAwIBAgI....etc"
        }
        {
          "guid": "a8ee01e33e3e3e3303e3",
          "issuer": "Pivotal",
          "created_on": "2017-04-09",
          "expires_on": "2021-04-09",
          "active": false,
          "cert_pem": "-----BEGIN CERTIFICATE-----\zBBBC+eAAAe1gAwAAAeZ....etc"
        }
      ]
    }
    
    Identify your newly added CA, which has active set to false. Record its GUID.

  4. Navigate to https://OPS-MAN-FQDN in a browser and log in to Ops Manager.

  5. Click Apply Changes. When the deploy finishes, continue to the next section.

Step 2: Activate the New CA

  1. Use curl to make an API call to activate the new CA, replacing CERT-GUID with the GUID of your CA that you retrieved in the previous section:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/CERT-GUID/activate" \
      -X POST \
      -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}' 
    
    The API returns a successful response:
    HTTP/1.1 200 OK

  2. List your root CAs to confirm that the new CA is active:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    Examine the response to ensure that your new CA has active set to true.

Step 3: Regenerate Non-Configurable Certificates to Apply the New CA

  1. Use curl to make an API call to regenerate all non-configurable certificates and apply the new CA to your existing Ops Manager Director:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/active/regenerate" \
        -X POST \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN" \
        -H "Content-Type: application/json" \
        -d '{}'
    
    The API returns a successful response:
    HTTP/1.1 200 OK

  2. Navigate to Ops Manager and click Apply Changes. When the deploy finishes, continue to the next section.

Step 4: Delete the Old CA

  1. List your root CAs to retrieve the GUID of your old, inactive CA:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities" \
        -X GET \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    

  2. Use curl to make an API call to delete your old CA, replacing OLD-CERT-GUID with the GUID of your old, inactive CA:

    $ curl "https://OPS-MAN-FQDN/api/v0/certificate_authorities/:OLD-CERT-GUID" \
        -X DELETE \
        -H "Authorization: Bearer YOUR-UAA-ACCESS-TOKEN"
    
    The API returns a successful response.
    HTTP/1.1 200 OK

  3. Navigate to Ops Manager and click Apply Changes.

Create a pull request or raise an issue on the source for this page in GitHub