open-consul/website/source/docs/agent/encryption.html.markdown

87 lines
3.8 KiB
Markdown
Raw Normal View History

2014-02-08 00:41:03 +00:00
---
layout: "docs"
page_title: "Encryption"
sidebar_current: "docs-agent-encryption"
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
method of encryption is described on the [encryption internals page](/docs/internals/security.html).
There are two separate encryption systems, one for gossip traffic and one for RPC.
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
2015-02-01 03:05:00 +00:00
starting the Consul agent. The key can be set via the `encrypt` parameter: the
value of this setting is a configuration file containing the encryption key.
2015-02-01 03:05:00 +00:00
The key must be 16-bytes, Base64 encoded. As a convenience, Consul provides the
[`consul keygen`](/docs/commands/keygen.html) commmand to generate a
cryptographically suitable key:
2014-02-08 00:41:03 +00:00
```text
2014-02-18 23:30:07 +00:00
$ consul keygen
2014-02-08 00:41:03 +00:00
cg8StVXbQJ0gPvMd9o7yrg==
```
With that key, you can enable encryption on the agent. If encryption is enabled,
the output of [`consul agent`](/docs/commands/agent.html) will include "Encrypted: true":
2014-02-08 00:41:03 +00:00
```text
$ cat encrypt.json
{"encrypt": "cg8StVXbQJ0gPvMd9o7yrg=="}
$ consul agent -data=/tmp/consul -config-file encrypt.json
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'
Advertise addr: '10.1.10.12'
RPC addr: '127.0.0.1:8400'
HTTP addr: '127.0.0.1:8500'
DNS addr: '127.0.0.1:8600'
Encrypted: true
Server: false (bootstrap: 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.
2014-04-07 22:06:26 +00:00
# RPC Encryption with TLS
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
2015-02-01 03:05:00 +00:00
[this tutorial on generating both a CA and signing keys](https://langui.sh/2009/01/18/openssl-self-signed-ca/)
using OpenSSL. Note: client certificates must have
[Extended Key Usage](https://www.openssl.org/docs/apps/x509v3_config.html#extended_key_usage_) enabled
for client and server authentication.
2014-04-07 22:06:26 +00:00
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.
These modes are controlled by the [`verify_outgoing`](/docs/agent/options.html#verify_outgoing)
and [`verify_incoming`](/docs/agent/options.html#verify_incoming) options, respectively.
If [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) is set, agents verify the
authenticity of Consul for outgoing connections. Server nodes must present a certificate signed
by the certificate authority present on all agents, set via the agent's
[`ca_file`](/docs/agent/options.html#ca_file) option. All server nodes must have an
appropriate key pair set using [`cert_file`](/docs/agent/options.html#cert_file) and
[`key_file`](/docs/agent/options.html#key_file).
If [`verify_incoming`](/docs/agent/options.html#verify_incoming) is set, the servers verify the
authenticity of all incoming connections. All clients must have a valid key pair set using
[`cert_file`](/docs/agent/options.html#cert_file) and
[`key_file`](/docs/agent/options.html#key_file). Servers will
also disallow any non-TLS connections. To force clients to use TLS,
[`verify_outgoing`](/docs/agent/options.html#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.