Generated Certificates

This section describes the usage and configuration of on demand created certificates for the TLS/SSL service plans of an a9s Data Service that are signed by a Platform Operator configured CA.

A Platform Operator can define a CA via the configuration of the a9s SPI for the corresponding a9s Data Service. This CA is then used to sign the generated certificates of the a9s Data Service's Service Instances. To be able to do so, the Platform Operator has to provide both the CA certificate and the private key for that CA certificate. The CA can be a private CA that is only used internally.

For the list of the supported a9s Data Services and the Limitations please refer to the a9s TLS/SSL Service Plans overview.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Installation

In order to use a CA for an a9s Data Service, the Ops file <data_service_name>-service/ops/use-ca.yml MUST be applied to the corresponding a9s Data Service deployment manifest.

data_service=<data_service_name>-service

bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-ca.yml

The Ops file uses the CredHub variable /a9s_<data_service_name>_service_spi_ca. The CredHub variable MUST be of type certificate. The option certificate is used to set ca.certificate and the option private is used to set ca.private_key. The CredHub variable MUST be set manually if you want to use your own CA, otherwise CredHub will generate one.

credhub set -n /a9s_${data_service}_spi_ca -t certificate -c ~/certs/chain.pem -p ~/certs/ca-key.pem

Configuration

Each a9s SPI provides the following properties to configure a CA:

Property	Note
ca.certificate	The ordered certificate chain which is used to sign the generated service instance certificates.The individual X.509 certificates MUST be in PKCS#1 format and PEM encoded. The first certificate MUST be the CA certificate that SHOULD be used for signing the generated certificates. The last certificate MUST be the root CA certificate. If the certificate chain only contains a root CA, then the root CA is also used for signing.
ca.private_key	The private key for the signing certificate in ca.certificate. The private key MUST be in PKCS#1 format and PEM encoded. The private key MUST NOT be encrypted.

ca:
  certificate: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    ...
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

Rotation

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

Certificate Rotation

The generated certificates are either automatically or manually rotated.

Automatic Certificate Rotation

The certificate of an individual service instance is automatically rotated when the service instance is updated via a cf update-service for example, and the certificate is about to expire soon.

Manual Certificate Rotation

The certificate of an individual service instance can be manually rotated by using the custom parameter force_certificate_rotation:

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

CA Rotation

The procedure below rotates the CA and the related certificates across all service instances. It can be used whether the certificates are still valid or have already expired.

When the certificates are still valid this should cause, from the application's point of view, for non-single service instances no downtime, or if any it will be negligible.

Step 1: Append the new CA to the old CA

Concatenate the old and the new CA (first old CA, then new CA) and set it as the certificate option of the CredHub variable /a9s_<data_service_name>_service_spi_ca. This allows the service instance's nodes and the clients to trust the generated certificate presented by the service instance that can be either signed by the new or the old CA.

cat ~/certs/chain-old.pem ~/certs/chain-new.pem > ~/certs/chain.pem
credhub set -n /a9s_${data_service}_spi_ca -t certificate -c ~/certs/chain.pem -p ~/certs/ca-key-old.pem

To apply the old and the new CA, the corresponding a9s Data Service MUST be redeployed.

bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-ca.yml

Step 2: Roll out both, the old and the new CA, to each service instance

There are two options to update the CA of the corresponding service instances of an a9s Data Service:

1. An individual service instance is automatically updated when the Application Developer updates their service instance, for example, via a cf update-service
2. The Platform Operator can update all service instances 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.

Renew Service Bindings

Before continuing with the next step, all service bindings MUST be renewed to propagate the new CA to the clients, unless the new CA is already trusted by the client's runtime.

Step 3: Replace the signing CA

Concatenate the new and the old CA (first new CA, then old CA) and set it as the certificate option of the CredHub variable /a9s_<data_service_name>_service_spi_ca. Additionally, set the private option of the CredHub variable /a9s_<data_service_name>_service_spi_ca to the private key of the new signing CA. This ensures that the new CA is used to sign the newly generated certificates. Furthermore, this allows the service instance's nodes and the clients to trust the generated certificate presented by the service instance that can be either signed by the new or the old CA.

cat ~/certs/chain-new.pem ~/certs/chain-old.pem > ~/certs/chain.pem
credhub set -n /a9s_${data_service}_spi_ca -t certificate -c ~/certs/chain.pem -p ~/certs/ca-key-new.pem

To apply the new and the old CA, the corresponding a9s Data Service MUST be redeployed.

bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-ca.yml

Step 4: Regenerate all certificates of the service instances

There are two options to update the generated certificate of the corresponding service instances of an a9s Data Service:

1. An individual service instance is automatically updated when the Application Developer updates their service instance, for example, via a cf update-service
2. The Platform Operator can update all service instances 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 5: Remove the old CA

Set the certificate option of the CredHub variable /a9s_<data_service_name>_service_spi_ca to only contain the new CA. This SHOULD be used to sign the newly generated certificates. The old CA is no longer needed since all existing service instances are only using certificates that are signed by the new CA.

credhub set -n /a9s_${data_service}_spi_ca -t certificate -c ~/certs/chain-new.pem -p ~/certs/ca-key-new.pem

To apply only the new CA, the corresponding a9s Data Service MUST be redeployed.

bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-ca.yml

Step 6: Roll out only the new CA to each service instance

There are two options to update the CA of the corresponding service instances of an a9s Data Service:

1. An individual service instance is automatically updated when the Application Developer updates their service instance, for example, via a cf update-service
2. The Platform Operator can update all service instances 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.

Renew Service Bindings

To continue using your service instances, all service bindings SHOULD be renewed to clean up the old CA from the clients.