certificates.md (6833B)
1 # Provisioning TLS certificates 2 3 As explained in the [deployment considerations](../getting_started/index.md), federation requires the use of TLS as most instances refuse to federate over unencrypted transports. 4 5 GoToSocial comes with built-in support for provisioning and renewing its own TLS certificates through Lets Encrypt. This guide looks at how you can provision your own certificates independently from GoToSocial. This can be useful if you want full control over how the certificates are provisioned, or because you're using a [reverse proxy](../getting_started/reverse_proxy/index.md) which is doing TLS termination. 6 7 There are a few different ways you can get TLS certificates: 8 9 * Buy them from a vendor, typically valid for 2 years 10 * Get them from your cloud provider, validity depends on their product constraints 11 * Get them from an [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment)-compatible provider like Lets Encrypt, typically valid for 3 months at a time 12 13 In this guide we'll only look at option 3, an ACME-compatible vendor. 14 15 ## General approach 16 17 The way you'll provision certificates through Lets Encrypt is: 18 19 * Install an ACME client on your server 20 * Configure the ACME client to provision your certificates 21 * Configure a piece of software to use those certificates 22 * Enable a timer/cron to regularly renew the certificates 23 * Signal to the necessary applications they need to reload or restart to pick up the new certificates 24 25 Certificates are provisioned [using a challenge](https://letsencrypt.org/sv/docs/challenge-types/), a way to verify that you're requesting a certificate for a domain you control. You'll typically use one of: 26 27 * HTTP challenge 28 * DNS challenge 29 30 The HTTP challenge requires serving certain files on port 80 on the domains you're requesting a certificate for under the `/.well-known/acme/` path. This is the default challenge type. 31 32 The DNS challenge happens entirely out of band but requires you to update a DNS TXT record. This approach is only feasible if your DNS registrar provides an API through which you can modify DNS records so that your ACME client can complete this challenge. 33 34 ## Clients 35 36 The official Lets Encrypt client is [certbot](https://certbot.eff.org/) and it's usually packaged in [your (Linux) distribution](https://repology.org/project/certbot/versions) of choice. Certain reverse proxies like Caddy and Traefik have built-in support for provisioning certificates using the ACME protocol. 37 38 A couple of other clients of note that you can consider using: 39 40 * [acme-client](https://man.openbsd.org/acme-client.1) for OpenBSD using the privilege separation features of the platform 41 * [lacme](https://git.guilhem.org/lacme/about/), which is built with process isolation and minimal privileges in mind in the same vein as acme-client but for Linux 42 * [Lego](https://github.com/go-acme/lego), an ACME client and library written in Go 43 * [mod_md](https://httpd.apache.org/docs/2.4/mod/mod_md.html), when using Apache 2.4.30+ 44 45 ### DNS challenge 46 47 For the DNS challenge, the API of your registrar needs to be supported by your ACME client. Though certbot has a few plugins for popular providers, you probably want to look at the [dns-multi](https://github.com/alexzorin/certbot-dns-multi) plugin instead. It leverages [Lego](https://github.com/go-acme/lego) under the hood which supports a much wider array of providers. 48 49 ## Configuration 50 51 There are 3 configuration options that are important: 52 53 * [`letsencrypt-enabled`](../configuration/tls.md) controls if GoToSocial will try to provision its own certificates 54 * [`tls-certificate-chain`](../configuration/tls.md) filesystem path where GoToSocial can find the TLS certificate chain + the public key 55 * [`tls-certificate-key`](../configuration/tls.md) filesystem path where GoToSocial can find the associated TLS private key 56 57 ### Without reverse proxy 58 59 When running GoToSocial directly exposed to the internet, but you still want to use your own certificates you can set the following options: 60 61 ```yaml 62 letsencrypt-enabled: false 63 tls-certificate-chain: "/path/to/combined-certificate-chain-public.key" 64 tls-certificate-key: "/path/to/private.key" 65 ``` 66 67 This disables the built-in provisioning of certificates through Lets Encrypt and tells GoToSocial where to find the certificates on disk. 68 69 !!! tip 70 Restart GoToSocial after renewing your certificates. It won't pick up on certificate rotation by itself when they are provided like this. 71 72 ### With reverse proxy 73 74 When running GoToSocial behind a [reverse proxy](../getting_started/reverse_proxy/index.md) which you also use for TLS termination, you'll need the following instead: 75 76 ```yaml 77 letsencrypt-enabled: false 78 tls-certificate-chain: "" 79 tls-certificate-key: "" 80 ``` 81 82 It's important to ensure the `tls-certificate-*` options are unset or set to the empty string. Otherwise GoToSocial will attempt to handle TLS itself. 83 84 !!! danger "Protocol configuration option" 85 Do **not** change the [`protocol`](../configuration/general.md) configuration option to `http`. This should only ever by set to `http` for development purposes. It needs to be set to `https` even when running behind a TLS-terminating reverse proxy. 86 87 You'll also want to change the [`port`](../configuration/general.md) GoToSocial binds on, so it no longer tries to use port 443. 88 89 To configure TLS in your reverse proxy, please refer to their documentation: 90 91 * [nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) 92 * [apache](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) 93 * [Traefik](https://doc.traefik.io/traefik/https/tls/) 94 * [Caddy](https://caddyserver.com/docs/caddyfile/directives/tls) 95 96 !!! tip 97 When configuring TLS in your reverse proxy, ensure you configure a reasonably modern set of compatible versions and ciphers. You can use the "Intermediate" configuration from the [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/). 98 99 Check the documentation of your reverse proxy on whether you have to reload or restart it after certificates have changed. Not all reverse proxies detect this. 100 101 ## Guides 102 103 There are a number of good resources on the internet explaining how to set all of this up. 104 105 * [ArchWiki entry](https://wiki.archlinux.org/title/certbot) on certbot 106 * [Gentoo wiki entry](https://wiki.gentoo.org/wiki/Let%27s_Encrypt) on Lets Encrypt 107 * [Linode guide](https://www.linode.com/docs/guides/enabling-https-using-certbot-with-nginx-on-fedora/) on certbot for Fedora, RHEL/CentOS, Debian and Ubuntu 108 * Digital Ocean guides on Lets Encrypt on Ubuntu 22.04 with [nginx](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04) or [apache](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-22-04)