Wildcard Certificates

This section describes the usage and configuration of a wildcard certificate for the TLS/SSL service plans of an a9s Data Service.

A Platform Operator can define a wildcard certificate via the configuration of the a9s SPI for the corresponding a9s Data Service. This wildcard certificate is then used for all Service Instances across all versions of the corresponding a9s Data Service.

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 wildcard certificate for an a9s Data Service, the Ops file <data_service_name>-service/ops/use-wildcard-certificate.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-wildcard-certificate.yml

The CredHub variable /a9s_<data_service_name>_service_spi_wildcard MUST be set to use the Ops file. The CredHub variable MUST be of type certificate. The option certificate is used to set wildcard.certificate, the option private is used to set wildcard.private_key, and the option root is used to set wildcard.ca.

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

Configuration

Each a9s SPI provides the following properties to configure a wildcard certificate:

Property	Note
wildcard.certificate	The single wildcard certificate (server/leaf certificate) that is used for all Service Instances. The X.509 certificate MUST be in PKCS#1 format and PEM encoded.
wildcard.private_key	The private key for the wildcard.certificate. The private key MUST be in PKCS#1 format and PEM encoded. The private key MUST NOT be encrypted.
wildcard.ca	The ordered certificate chain for the wildcard.certificate. The individual X.509 certificates MUST be in PKCS#1 format and PEM encoded. The first certificate MUST be the CA certificate that signed the certificate in wildcard.certificate. The last certificate MUST be the root CA certificate. The certificate chain can also only consist of the root CA.

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

Common Name And Subject Alternative Name

The wildcard certificate MUST meet the following requirements as it is used to verify all internal communication between the cluster nodes. Furthermore, as the service instance hostnames are propagated to the applications via the service bindings, they provide a way to verify the server they are connecting to.

• The Common Name (CN) of the wildcard certificate MUST be set to *.node.dc1.<iaas.consul.domain>.
• The Subject Alternative Name (SAN) of the wildcard certificate MUST contain the DNS name entries *.node.dc1.<iaas.consul.domain> and *.service.dc1.<iaas.consul.domain>.

All a9s Data Services with a vendored dashboard MUST contain an additional SAN entry to enable them correctly.

This affects the following a9s Data Services:

• a9s Messaging
  • *.<dashboard_hostname>.<iaas.cf.system_domain>
• a9s LogMe2
  • <dashboard_hostname>.<iaas.cf.system_domain>

Only the a9s Messaging dashboard needs a leading *, because the url will contain the id of the service instance.

The <dashboard_hostname> property will be the name of the a9s Data Service deployment, like rabbitmq-service. And the <iaas.cf.system_domain> property can be found in the infrastructure configuration file, where it is set for the whole environment.

Rotation

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

Certificate Rotation

The procedure below rotates only the wildcard certificate across all Service Instances and keeps the CA. It can be only used when the wildcard certificate is still valid.

danger

Always rotate the wildcard certificate before it expires, as rotating an expired wildcard certificate will lead to a failure and your a9s Data Service will be in a broken state.

When the wildcard certificate is 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.

Prerequisite

The new wildcard certificate MUST be signed by the same CA as the current wildcard certificate.

Step 1: Update the wildcard certificate

Set the certificate and private options of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard to the new wildcard certificate to use and the corresponding private key.

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

To apply the new wildcard certificate, 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-wildcard-certificate.yml

Step 2: Redeploy each service instance

There are two options to update the wildcard 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.

CA Rotation

The procedure below rotates the CA and the related wildcard certificate across all Service Instances. It can be only used when the CA and the wildcard certificate is still valid.

danger

Always rotate the CA and the related wildcard certificate before they expire, as rotating an expired CA or the related wildcard certificate will lead to a failure and your a9s Data Service will be in a broken state.

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 root option of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard. This allows the service instance's nodes and the clients to trust the wildcard 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_wildcard -t certificate -c ~/certs/cert-old.pem -p ~/certs/cert-key-old.pem -r ~/certs/chain.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-wildcard-certificate.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 wildcard certificate

Set the certificate and private options of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard to the new wildcard certificate that is signed by the new CA to use and the corresponding private key.

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

To apply the new wildcard certificate, 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-wildcard-certificate.yml

Step 4: Roll out the new wildcard certificate to each service instance

There are two options to update the wildcard 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 root option of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard to only contain the new CA. The old CA is no longer needed since all existing Service Instances are only using the new wildcard certificate that is signed by the new CA.

credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert-new.pem -p ~/certs/cert-key-new.pem -r ~/certs/chain-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-wildcard-certificate.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.