open-consul/website/pages/docs/agent/encryption.mdx

115 lines
6.0 KiB
Plaintext
Raw Normal View History

2014-02-08 00:41:03 +00:00
---
2020-04-07 18:55:19 +00:00
layout: docs
page_title: Encryption
sidebar_title: Encryption
2020-04-07 18:55:19 +00:00
description: >-
The Consul agent supports encrypting all of its network traffic. The exact
method of encryption is described on the encryption internals page. There are
two separate encryption systems, one for gossip traffic and one for RPC.
2014-02-08 00:41:03 +00:00
---
# Encryption
2014-02-18 23:30:07 +00:00
The Consul agent supports encrypting all of its network traffic. The exact
2020-04-09 23:46:54 +00:00
method of encryption is described on the [encryption internals page](/docs/internals/security).
There are two separate encryption systems, one for gossip traffic and one for RPC.
To configure the encryption systems on a new cluster, review this following guides to
2020-04-06 20:27:35 +00:00
[enable gossip encryption](https://learn.hashicorp.com/consul/security-networking/agent-encryption?utm_source=consul.io&utm_medium=docs) and
[TLS encryption for agent communication](https://learn.hashicorp.com/consul/security-networking/certificates?utm_source=consul.io&utm_medium=docs).
2014-02-08 00:41:03 +00:00
2014-04-07 22:06:26 +00:00
## Gossip Encryption
2014-02-08 00:41:03 +00:00
2014-04-07 22:06:26 +00:00
Enabling gossip encryption only requires that you set an encryption key when
starting the Consul agent. The key can be set via the `encrypt` parameter.
2018-03-02 15:41:09 +00:00
~> **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
2020-04-09 23:46:54 +00:00
[`consul keygen`](/docs/commands/keygen) command to generate a
cryptographically suitable key:
2014-02-08 00:41:03 +00:00
2020-05-19 18:32:38 +00:00
```shell-session
2014-02-18 23:30:07 +00:00
$ consul keygen
pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
2014-02-08 00:41:03 +00:00
```
With that key, you can enable encryption on the agent. If encryption is enabled,
2020-04-09 23:46:54 +00:00
the output of [`consul agent`](/docs/commands/agent) will include "Encrypt: true":
2014-02-08 00:41:03 +00:00
2020-05-19 18:32:38 +00:00
```shell-session
$ cat encrypt.json
{"encrypt": "pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s="}
$ consul agent -data-dir=/tmp/consul -config-file=encrypt.json
2016-03-07 20:23:45 +00:00
==> WARNING: LAN keyring exists but -encrypt given, using keyring
==> WARNING: WAN keyring exists but -encrypt given, using keyring
2014-02-18 23:30:07 +00:00
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!
Node name: 'Armons-MacBook-Air.local'
Datacenter: 'dc1'
Server: false (bootstrap: false)
2016-03-07 20:23:45 +00:00
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
2014-02-08 00:41:03 +00:00
...
```
2014-02-18 23:30:07 +00:00
All nodes within a Consul cluster must share the same encryption key in
2014-02-08 00:41:03 +00:00
order to send and receive cluster information.
## Configuring Gossip Encryption on an existing cluster
As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster
2020-04-06 20:27:35 +00:00
through the following process. Review this [step-by-step guide](https://learn.hashicorp.com/consul/security-networking/agent-encryption#enable-gossip-encryption-existing-cluster)
Encryption Docs and New Guide (#5059) * Added the new encryption guide, updated the encryption docs, updated the side-nav and index page for new guide. * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Making updates based on feedback * Updating language * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Removing all reload mentions * Updated the final remarks about TLS encryption to include a note about HTTP connections * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/agent-encryption.html.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * removed the mention of cfssl * also removed the bit about cfssl in the doc * updating cert names * updated all cert values
2018-12-19 18:41:25 +00:00
to encrypt gossip on an existing cluster.
## RPC Encryption with TLS
2014-04-07 22:06:26 +00:00
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
2020-04-06 20:27:35 +00:00
[this tutorial on generating both a CA and signing keys](https://learn.hashicorp.com/consul/security-networking/certificates).
2014-04-07 22:06:26 +00:00
~> 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.
2015-02-01 03:05:00 +00:00
TLS can be used to verify the authenticity of the servers or verify the authenticity of clients.
2020-04-09 23:46:54 +00:00
These modes are controlled by the [`verify_outgoing`](/docs/agent/options#verify_outgoing),
[`verify_server_hostname`](/docs/agent/options#verify_server_hostname),
and [`verify_incoming`](/docs/agent/options#verify_incoming) options, respectively.
2020-04-09 23:46:54 +00:00
If [`verify_outgoing`](/docs/agent/options#verify_outgoing) 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
2020-04-09 23:46:54 +00:00
[`ca_file`](/docs/agent/options#ca_file) and [`ca_path`](/docs/agent/options#ca_path)
options. All server nodes must have an appropriate key pair set using [`cert_file`](/docs/agent/options#cert_file) and [`key_file`](/docs/agent/options#key_file).
2020-04-09 23:46:54 +00:00
If [`verify_server_hostname`](/docs/agent/options#verify_server_hostname) is set, then
2015-05-11 23:22:10 +00:00
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
2015-05-11 23:22:10 +00:00
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
2015-05-11 23:22:10 +00:00
to true, and generate the proper certificates, but this is defaulted to false to avoid breaking
existing deployments.
2020-04-09 23:46:54 +00:00
If [`verify_incoming`](/docs/agent/options#verify_incoming) is set, the servers verify the
authenticity of all incoming connections. All clients must have a valid key pair set using
2020-04-09 23:46:54 +00:00
[`cert_file`](/docs/agent/options#cert_file) and
[`key_file`](/docs/agent/options#key_file). Servers will
also disallow any non-TLS connections. To force clients to use TLS,
2020-04-09 23:46:54 +00:00
[`verify_outgoing`](/docs/agent/options#verify_outgoing) must also be set.
2014-04-07 22:06:26 +00:00
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.
## Configuring TLS on an existing cluster
As of version 0.8.4, Consul supports migrating to TLS-encrypted traffic on a running cluster
without downtime. This process assumes a starting point with no TLS settings configured and involves
an intermediate step in order to get to full TLS encryption. Review the
[Securing RPC Communication with TLS Encryption guide](https://learn.hashicorp.com/consul/security-networking/certificates)
for the step-by-step process to configure TLS on a new or existing cluster. Note the call outs there
2020-04-06 20:27:35 +00:00
for existing cluster configuration.