TLS Certificates

freistilbox encrypts traffic between your visitors and the platform using TLS certificates. You can choose between free automated certificates from Let’s Encrypt or your own custom certificates, for example if you need an organisation-validated or wildcard certificate.

TLS is terminated at the edge routers, so your application boxes don’t spend resources on encryption. Caching works the same for encrypted and unencrypted requests.

Table of Contents

TLS modes

Each website has a TLS mode that controls how certificates are handled:

  • None – no TLS certificate is configured. Visitors can only reach the website over plain HTTP.
  • Let’s Encrypt – freistilbox obtains and renews a free domain-validated certificate automatically. This is the recommended option for most websites.
  • Custom – you provide your own PEM-encoded certificate, private key, and optional certificate chain. Use this when you need an organisation-validated certificate, an extended-validation certificate, or a wildcard certificate.

Setting the TLS mode

  1. Open the website’s detail page in the dashboard.
  2. Click Edit.
  3. In the TLS certificate section, select the mode you want: None, Let’s Encrypt, or Custom.
  4. Click Update.

The change takes effect within a few minutes.

Let’s Encrypt certificates

Prerequisites

Before you can enable Let’s Encrypt, two conditions must be met:

  • DNS must point to freistilbox. Let’s Encrypt validates your domain by connecting to the edge router. At a minimum, the main domain of your website must resolve to freistilbox. See the DNS setup documentation for details.
  • CAA records must allow Let’s Encrypt. If your domain has CAA DNS records, they must include letsencrypt.org as a permitted certificate authority. A missing or restrictive CAA record will prevent Let’s Encrypt from issuing a certificate. If you haven’t set any CAA records, no change is needed – the default is to allow all CAs.
  • The edge router must support Let’s Encrypt. If the Let’s Encrypt option is grayed out in the dashboard, the edge router serving your website doesn’t support it yet. Contact support to coordinate the necessary changes.

Auxiliary domains that don’t resolve to freistilbox will be left off the certificate. If the main domain can’t be validated, no certificate is issued at all.

Enabling Let’s Encrypt

  1. Make sure DNS for your domain(s) points to freistilbox.
  2. Open the website’s detail page and click Edit.
  3. Select Let’s Encrypt as the TLS mode.
  4. Click Update.

After a few minutes, your website will be reachable via https://.

Certificate renewal

Let’s Encrypt certificates are valid for 90 days. freistilbox renews them automatically when they enter the last 30 days of their lifetime. No action is required on your part.

Custom certificates

When to use a custom certificate

Let’s Encrypt issues domain-validated certificates only. Choose a custom certificate when:

  • You need an organisation-validated (OV) or extended-validation (EV) certificate.
  • You want a wildcard certificate (e.g. *.example.com) to cover a growing list of subdomains.
  • Your certificate authority is not Let’s Encrypt.

Uploading a custom certificate

  1. Open the website’s detail page and click Edit.
  2. Select Custom as the TLS mode. Three text areas appear.
  3. Paste the following PEM-encoded data:
    • Certificate (required) – your server certificate.
    • Private key (required) – the private key that matches the certificate.
    • Certificate chain (optional) – any intermediate certificates your CA provided.
  4. Click Update.

The certificate is validated before it is saved. If there is a problem, the dashboard will show an error message and the certificate will not be applied.

Validation checks

When you submit a custom certificate, the dashboard checks that:

Check Error if it fails
Certificate is valid PEM “is not a valid PEM certificate”
Private key is valid PEM “has an invalid private key”
Private key matches the certificate “does not match the private key”
Certificate has not expired “has expired”
Certificate covers all website domains (main + auxiliary), including wildcard matching “does not cover all domains”
Chain is valid PEM (if provided) “has an invalid certificate chain”

Fix the reported issue and submit again.

Replacing a certificate

To replace an expiring or compromised certificate, open the website edit page, paste the new PEM data into the same fields, and click Update. The old certificate is overwritten.

Removing a custom certificate

To stop using a custom certificate, change the TLS mode to None or Let’s Encrypt and click Update.

Handling HTTPS in your application

Because TLS is terminated at the edge routers, your application boxes always receive plain HTTP requests. The edge routers add an X-Forwarded-Proto: https header to requests that arrived over TLS. The application boxes translate this into an environment variable named HTTPS set to on.

Detecting HTTPS in PHP 

if ($_SERVER['HTTPS'] == "on")

This variable is also set by PHP for native SSL requests, so existing applications, plugins, and modules should work without changes.

Detecting HTTPS in .htaccess

Apache’s built-in RewriteCond %{HTTPS} checks whether the request reached the box encrypted, which is never the case with TLS offloading. You need to check the environment variable of the same name instead.

This will not work:

RewriteCond %{HTTPS} on

This will work:

RewriteCond %{ENV:HTTPS} on

To cover both cases:

RewriteCond %{HTTPS} on [OR]
RewriteCond %{ENV:HTTPS} on

Redirecting all requests to HTTPS

To force HTTPS for every request, add the following to your .htaccess file:

RewriteCond %{HTTPS} !on
RewriteCond %{ENV:HTTPS} !on
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]