SSL certificates

Modified on: Fri, 30 Jun, 2023 2:26 PM

SSL certificates allow your site visitors to make requests to your site in a secure manner. This is especially important on websites that contain login features, or anything capturing submissions of user’s personal information. If an SSL certificate is used, the connection between the user and the server is secure, and any eavesdropping is made difficult.

By default, a certificate is setup for the “internal” URL of an environment, e.g. https://<stack>-uat.sites.silverstripe.com where <stack> is the stack code of your Silverstripe Cloud stack.

For production environments, or any other environments running on a custom domain, you will need a new certificate, either by setting up Let’s Encrypt or providing an existing certificate if you already have one.

The state of an environment’s certificate can be viewed by going to Silverstripe Cloud, and viewing the “SSL” tab of your environment.

Free certificates using Let’s Encrypt

Let’s Encrypt is a free service for generating SSL certificates for your website. These certificates are automatically renewed every three months, requiring no intervention on your part once set up.

As part of setting up Let’s Encrypt you’ll need to add a verification DNS record for each domain you want your certificate to cover. This can be done through your DNS provider, and these records must remain in place in order for your certificate to automatically renew itself.

The following apply to the Let’s Encrypt service:

Up to 100 hostnames per certificate.
Wildcard domains are not supported, such as *.example.com. Only root domains and subdomains are supported, such as example.com, www.example.com, and foo.www.example.com.
Verifying your domains and provisioning your certificate may take up to 12 hours.
If your environment has a WAF, it must be managed by Silverstripe for your Let’s Encrypt certificate to be applied to it.
If a domain name is covered by a CAA DNS record, it must contain letsencrypt.org or else a certificate cannot be provisioned for that domain name.

Adding domains to your certificate

In the “SSL” tab of your environment, select the “Configure Let’s Encrypt” button to show the Let’s Encrypt domains that have been set up for your environment.

Enter each domain name you want to cover on its own line and select the “Add domain” button. For each domain, the associated www subdomain can also be automatically included without the need to specify it.

Your domains are then added to the table, with an associated CNAME record for each one. These records are initially in the “Pending verification” state until you add these records to your DNS provider and our infrastructure validates their existence.

Once your domains have all been verified, our infrastructure will request a certificate from Let’s Encrypt and provison it to your environment and WAF if applicable. This process is automatic and does not require a deployment. Any existing certificate for your environment remains in place until the Let’s Encrypt certificate has been provisioned.

Changing domain names for your certificate

Changing the covered domain names for your certificate can be done at any time using the same process as above. Once the new domain names have their verification DNS records added and validated, or when domain names have been removed, we’ll request a new certificate from Let’s Encrypt and provision it to your environment.

Renewing your Let’s Encrypt certificate

The renewal process for Let’s Encrypt certificates is completely automated. As long as the verification DNS records are still in place, our infrastructure will request and provision a new certificate for your environment.

Custom certificates

If you cannot use Let’s Encrypt or prefer to have your own custom certificate, you can purchase your own certificate through a certificate vendor and upload it to your environment. Please note that currently, we support only 2048-bit RSA keys.

Choosing this option means that you will own the purchase, implementation, and management of the certificate. You need to be aware that:

Silverstripe doesn't Monitor Custom Certificate expiry dates. We recommend implementing an SSL monitoring tool If you have Custom Certificate Setup
We recommend that you start your certificate renewal process no less than 30 days before expiry and book your implementation no less than two weeks before expiry. This will leave time to address any issues that may be found as part of sourcing and implementing your certificate.
We recommend that you lodge a service request via the portal to let us know when you intend to implement the certificate. This will help us to rapidly diagnose any issues arising from the change.

Generating a certificate signing request (CSR) for custom certificates

In order to purchase a custom certificate from a vendor of your choice, you’ll need to generate a certificate signing request (CSR) which outlines the ownership of the certificate and the domains it covers. Your vendor will typically have instructions or a step-by-step wizard to generate a CSR.

If you have openssl installed you can use the following command to generate a CSR as server.csr and a private key called server.key. You’ll be prompted for information about your organization that will be used for the certificate:

$ openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr

-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]: NZ
State or Province Name (full name) [Some-State]: Wellington
Locality Name (eg, city) []:Wellington
Organization Name (eg, company) [Internet Widgits Pty Ltd]: CompuGlobalHyperMegaNet Ltd
Organizational Unit Name (eg, section) []: IT
Common Name (e.g. server FQDN or YOUR name) []: www.compuglobalhypermeganet.com

The resulting server.csr is provided to your SSL certificate vendor to generate your certificate, which can then be uploaded to your environment alongside the server.key private key file.

It’s important that you store your private key in a secure manner and do not lose it. The certificate cannot be used without the private key.

Formatting certificate bundles

Cloud accepts certificates formatted as PEM only. Files formatted this way will usually have .pem, .crt, or .cer extensions. You can also recognize this format by its distinct text delimiters - a single certificate will look like this:

-----BEGIN CERTIFICATE-----
MIIEqDCCApCgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwKjEoMCYGA1UEAwwfU...
<Base64 encoded certificate>
-----END CERTIFICATE-----

Certificates are usually provided as bundles, but sometimes you may need to prepare such a bundle yourself. This is needed because additional (“intermediary”) certificates are required to establish trust (“chain of authority”) between the certificate for your domain, and the certificate installed in the browser (“root”).

Silverstripe Cloud will attempt to resolve these certificates automatically for you, but you can add them yourself by manually inserting your certificate bundle into the certificate field when uploading.

The only compliant way of formatting such a bundle is for your certificate to come first, and then each appended certificate must directly certify the one preceding it. The only certificate that may be skipped is the final (root) certificate, under the assumption the browser must already have it.

Example of a valid certificate bundle for pasting into Silverstripe Cloud:

Steps Before Uploading Certificate

Please take a backup of your Existing Certificate and Key by creating a Service Desk ticket.

Before Uploading the certificate, Please Follow the below steps to make sure the Key and Certificate have matching Values.

For Checking Certificate Value
openssl x509 -noout -modulus -in ssl_certificate.crt | openssl md5
For Checking  Key Value
openssl rsa -noout -modulus -in key.key | openssl md5

If it doesn't, check the csr was matching, etc:

openssl req -noout -modulus -in CSR_file.csr | openssl md5

If the certificate and key value do not match, Please do not try to upload on the Cloud Dashboard. This might affect the Website's availability or the Service can be degraded. You have to get in touch with your SSL Provider to Check the details again.

Uploading your custom certificate

In the “SSL” tab of your environment, select the “Configure custom certificate” button to upload your private key and certificate. Note that any certificate or private key uploaded is stored securely.

Once complete, the certificate will be provisioned onto your environment and your WAF if applicable. This process may take up to one minute to complete.

Redirecting to SSL on your website

The cloud can redirect all requests on the http:// protocol for a particular domain to the https:// protocol. See Domains on how to configure this through Silverstripe Cloud.