Public DNS setup
Before you begin
Keyless has been tested on
arm architectures. The key server binary will likely run on all architectures that Go supports. Code support may exist for other CPUs too, but these other architectures have not been tested.
In addition to running on bare metal, the key server should run without issue in a virtualized or containerized environment. Care will need to be taken to configure ingress access to the appropriate TCP port and file system access to private keys (if using filesystem storage).
Supported operating systems
You will need to have a supported operating system (OS) to run Keyless. Supported operating systems include:
- Ubuntu 14.04 LTS, 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS, 22.10
- Debian 8, 9, 10, 11, 12
- RHEL and CentOS 6, 7, 8, 9
- Amazon Linux 1, 2
We strongly recommend that you use an operating system still supported by the vendor (still receiving security updates) as your key server will have access to your private keys.
Step 1 - Create public DNS record
- Open a Terminal and run
openssl rand -hex 24to generate a long, random hostname such as
- Add this record via your DNS provider’s interface as an A or AAAA record pointing to the IP address of your Keyless SSL server.
- Use this hostname as the server hostname during initialization of your Keyless SSL server.
Step 2 — Upload Keyless SSL Certificates
Before your key servers can be configured, you must next upload the corresponding SSL certificates to Cloudflare’s edge. During TLS termination, Cloudflare will present these certificates to connecting browsers and then (for non-resumed sessions) communicate with the specified key server to complete the handshake.
You will have to upload each certificate used with Keyless SSL.
To create a Keyless certificate in the dashboard:
- Log in to the and select your account and zone.
- Go to SSL/TLS > Edge Certificates.
- Select Upload Keyless SSL Certificate.
- Fill in the upload modal with the certificate and other details and select Add.
Step 3 — Set up and activate key server
Finally, you need to install the key server on your infrastructure, populate it with the SSL keys of the certificates you wish to use to terminate TLS at Cloudflare’s edge, and activate the key server so it can be mutually authenticated.
Debian or Ubuntu
$ sudo mkdir -p --mode=0755 /usr/share/keyrings$ curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null# Add this repo to your apt repositories$ echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/gokeyless buster main' | sudo tee /etc/apt/sources.list.d/cloudflare.list# install gokeyless$ sudo apt-get update && sudo apt-get install gokeyless
Use either of the following examples to install the
gokeyless package for RHEL or CentOS.
RHEL or CentOS (version lower than 8)
$ sudo yum makecache$ sudo yum-config-manager --add-repo https://pkg.cloudflare.com/gokeyless.repo && sudo yum-config-manager --setopt=gokeyless-stable.gpgkey=https://pkg.cloudflare.com/cloudflare-ascii-pubkey.gpg --save$ sudo yum install gokeyless
RHEL or CentOS (version 8 or higher)
$ sudo dnf install dnf-plugins-core && dnf clean all$ sudo dnf config-manager --add-repo https://pkg.cloudflare.com/gokeyless.repo$ sudo dnf install gokeyless
Add your Cloudflare account details to the configuration file located at
- Set the hostname of the key server, for example,
11aa40b4a5db06d4889e48e2f.example.com. This is also the value you entered when you uploaded your keyless certificate and is the hostname of your key server that holds the key for this certificate.
- Set the Zone ID (found on Overview tab of the Cloudflare dashboard).
Install your private keys in
/etc/keyless/keys/ and set the user and group to keyless with 400 permissions. Keys must be in PEM or DER format and have an extension of
$ ls -l /etc/keyless/keys-r-------- 1 keyless keyless 1675 Nov 18 16:44 example.com.key
When running multiple key servers, make sure all required keys are distributed to each key server. Customers typically will either use a configuration management tool such as Salt or Puppet to distribute keys or mount
/etc/keyless/keys to a network location accessible only by your key servers. Keys are read on boot into memory, so a network path must be accessible during the gokeyless process start/restart.
To activate, restart your keyless instance:
sudo service gokeyless restart
sudo /etc/init.d/gokeyless restart
Allow incoming connections from Cloudflare
During TLS handshakes, Cloudflare’s keyless client will initiate connections to the key server hostname or IP address you specify during certificate upload. By default, the keyless client will use a destination TCP port of 2407, but this can be changed during certificate upload or by editing the certificate details after upload.