Common SSL/TLS configuration

Supported Services

The following data services support SSL/TLS plans and share a common configuration interface for x509 certificates:

• Elasticsearch
• Harbor
• MongoDB
• PostgreSQL
• RabbitMQ
• MariaDB (10.4 only) - See Restrictions
• OpenSearch - See Restrictions

SSL/TLS Certificates

An x509 certificate for SSL service instances can be deployed in several ways. The following list is specified in order of preference, so that - if specified - a "user provided certificate" will be used before a "configured wildcard certificate". In other words, if a user has specified a certificate for a particular SSL service instance, they have to delete the certificate before another certificate can be deployed to the service instance.

Certificate Usage Order

1. User provided certificate
2. Configured wildcard certificate
3. Generated certificate with a configured intermediate certificate
4. Self-signed certificate

User Provided Certificates

The user can provide their own certificate as a parameter in the call to cf create-service or cf update-service. See app developer documentation.

Wildcard Certificate

A platform operator can define wildcard certificates in a deployment manifest (e.g. rabbitmq-service.yml). These are used when the user doesn't provide their own certificates (see User Provided Certificates).

...
properties:
...
  rabbitmq-spi:
    wildcard:
      # CA chain of the wildcard certificate
      ca: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      # Wildcard certificate
      cert: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      # Wildcard private key
      key: |
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

Note

• Only the Certificate Authority (CA) certificate(s) that are part of the CA chain to make the wildcard certificate valid should go into the CA property (ca). The CA chain might contain one or more certificates.
• Only the wildcard certificate should go into the certificate property (cert).
• Please note that the supplied key must not be encrypted! If your intermediate CA's key is encrypted with a password, please provide the decrypted version of the key. If you supply an encrypted key, you should see an error message similar to this:

$ cf create-service a9s-messaging310 rabbitmq-single-small-ssl rabbitmq1
Creating service instance rabbitmq1 in org test / space test as admin...
Service broker error: Neither PUB key nor PRIV key: nested asn1 error
FAILED

Rotating Wildcard Certificates

A platform operator can rotate the wildcard certificates and, if necessary, the CA itself when they are nearing expiration (or are already expired). This is possible following an approach similar to BOSH's NATS rotation

There are two main scenarios:

a. Rotating your wildcard certificates only b. Rotating your wildcard certificates and CA

Steps to rotate your wildcard certificates only:

1. Create a valid wildcard certificate and private key with the current CA
2. Replace your new wildcard certificate and private key to the existing one as follows:

...
properties:
...
  rabbitmq-spi:
    wildcard:
      ca: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      cert: |
        # New wildcard certificate
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        # New private key 
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

3. Redeploy the Data Service
4. Update the Service Instance via the CF CLI (for every Service Instance belonging to the Data Service)

cf update-service <your-service-instance> -c "{\"force_certificate_rotation\": \"true\"}"

After this both your Data Service and its Service Instances should only have the new certificate and private key in place. This should cause, from the application's point of view, no downtime, or if any it will be negligible.

Steps to rotate your wildcard certificates and the CA:

1. Create a valid wildcard certificate and private key with the new CA
2. Concatenate your new CA to the existing one as follows:

...
properties:
...
  rabbitmq-spi:
    wildcard:
      ca: |
        # Old CA 
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        # New CA 
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      cert: |
        # Old wildcard certificate
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        # Old key 
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

3. Redeploy the Data Service
4. Update the Service Instance via the CF CLI (for every Service Instance belonging to the Data Service)

cf update-service <your-service-instance> -c "{\"force_certificate_rotation\": \"true\"}"

5. By this point, both your Data Service and Service Instances, should have the concatenated CAs; so we can now replace the old wildcard certificate and private key for the one signed by the new CA

...
properties:
...
  rabbitmq-spi:
    wildcard:
      ca: |
        # Old CA 
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        # New CA 
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      cert: |
        # New wildcard certificate
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        # New key 
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

6. Redeploy the Data Service
7. Update the Service Instance via the CF CLI (for every Service Instance belonging to the Data Service)

cf update-service <your-service-instance> -c "{\"force_certificate_rotation\": \"true\"}"

8. After redeploying, both your Data Service and Service Instances, should have the concatenated CAs, the new wildcard certificate and private key; so we can now remove the old CA

...
properties:
...
  rabbitmq-spi:
    wildcard:
      ca: |
        # New CA 
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      cert: |
        # New wildcard certificate
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        # New key 
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

9. Redeploy the Data Service
10. Update the Service Instance via the CF CLI (for every Service Instance belonging to the Data Service)

cf update-service <your-service-instance> -c "{\"force_certificate_rotation\": \"true\"}"

After this both your Data Service and its Service Instances should only have the new certificate and private key in place. This should cause, from the application's point of view, no downtime, or if any it will be negligible.

TLS Certificate Creation

A data service can either create self signed certificates or create certificates derived from an intermediate certificate. For the latter the customer has to configure an intermediate certificate with their private key.

...
properties:
...
  rabbitmq-spi:
    intermediate-ca:
      cert: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: |
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

NOTE Please note that the supplied key must not be encrypted! (see above)

Self-signed Certificate

A supported data service instance using an SSL plan will create its own self-signed certificate, if no user leaf certificates or certificate authorities have been supplied.

Restrictions for MariaDB 10.4

MariaDB 10.4 has a pre-defined structure for how it expects the different certificates. This structure is described in the vendors' documentation:

• https://galeracluster.com/library/documentation/ssl-cert.html

These are the most important parts that we want to highlight:

There are three certificates that you need to create in order to secure Galera Cluster: the Certificate Authority (CA) key and cert; the server certificate, to secure mysqld activity and replication traffic; and the client certificate to secure the database client and stunnel for state snapshot transfers.

Due to the nature of our automation, one is only able to provide the intermediate-ca property which is used to create the server and client certificates. How to use the intermediate-ca property is explained here.

Please also ensure that the given intermediate-ca certificate is in the VMs trust store(s). The certificate can be distributed, for example, via the BOSH director.

Restrictions for OpenSearch

OpenSearch expects that the certificates' private keys are in the format PKCS#8. This restriction applies when one is using User Provided Certificates, Wildcard Certificate or TLS Certificate Creation as well as Self-signed Certificate. You can check the vendor's documentation for more information:

• https://opensearch.org/docs/latest/security-plugin/configuration/tls/
• https://opensearch.org/docs/latest/security-plugin/configuration/generate-certificates/