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 only used when the CA and the certificate is still valid.
Always rotate the CA and the related certificate before they expire, as rotating an expired CA or a related 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 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:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- 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 toprovisioned
.
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:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- 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 toprovisioned
.
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:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- 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 toprovisioned
.
To continue using your Service Instances, all service bindings SHOULD be renewed to clean up the old CA from the clients.