Encryption

To configure the encryption systems on a new cluster, review this following tutorials to enable gossip encryption and .

Enabling gossip encryption only requires that you set an encryption key when starting the Consul agent. The key can be set via the parameter.

WAN Joined Datacenters Note: If using multiple WAN joined datacenters, be sure to use the same encryption key in all datacenters.

The key must be 32-bytes, Base64 encoded. As a convenience, Consul provides the consul keygen command to generate a cryptographically suitable key:

$ cat encrypt.json
{"encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="}
$ consul agent -data-dir=/tmp/consul -config-file=encrypt.json
==> WARNING: LAN keyring exists but -encrypt given, using keyring
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!
        Datacenter: 'dc1'
       Client Addr: 127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, RPC: 8400)
      Cluster Addr: 10.1.10.12 (LAN: 8301, WAN: 8302)
    Gossip encrypt: true, RPC-TLS: false, TLS-Incoming: false
...

All nodes within a Consul cluster must share the same encryption key in order to send and receive cluster information.

As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster through the following process. Review this to encrypt gossip on an existing cluster.

Consul supports using TLS to verify the authenticity of servers and clients. To enable this, Consul requires that all clients and servers have key pairs that are generated by a single Certificate Authority. This can be a private CA, used only internally. The CA then signs keys for each of the agents, as in this tutorial on generating both a CA and signing keys.

Certificates need to be created with x509v3 extendedKeyUsage attributes for both clientAuth and serverAuth since Consul uses a single cert/key pair for both server and client communications.

If is set, agents verify the authenticity of Consul for outgoing connections. Server nodes must present a certificate signed by a common certificate authority present on all agents, set via the agent’s ca_file and options. All server nodes must have an appropriate key pair set using cert_file and .

If verify_server_hostname is set, then outgoing connections perform hostname verification. All servers must have a certificate valid for server.<datacenter>.<domain> or the client will reject the handshake. This is a new configuration as of 0.5.1, and it is used to prevent a compromised client from being able to restart in server mode and perform a MITM (Man-In-The-Middle) attack. New deployments should set this to true, and generate the proper certificates, but this is defaulted to false to avoid breaking existing deployments.

If is set, the servers verify the authenticity of all incoming connections. All clients must have a valid key pair set using cert_file and . Servers will also disallow any non-TLS connections. To force clients to use TLS, verify_outgoing must also be set.

TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP and is secured using a symmetric key. See above for enabling gossip encryption.