github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Substantial and potentially inaccurate rewrite to docs/agent/encryption.

pull/664/head
Ryan Breen 2015-01-31 18:33:29 -05:00
parent 255d763623
commit edeab6a0d2
1 changed files with 27 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
website/source/docs/agent/encryption.html.markdown
View File

@ -3,31 +3,31 @@ layout: "docs"
page_title: "Encryption" page_title: "Encryption"
sidebar_current: "docs-agent-encryption" sidebar_current: "docs-agent-encryption"
description: |- description: |-
The Consul agent supports encrypting all of its network traffic. The exact method of this encryption is described on the encryption internals page. There are two separate systems, one for gossip traffic and one for RPC. 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.
--- ---
# Encryption # Encryption
The Consul agent supports encrypting all of its network traffic. The exact The Consul agent supports encrypting all of its network traffic. The exact
method of this encryption is described on the method of encryption is described on the [encryption internals page](/docs/internals/security.html).
[encryption internals page](/docs/internals/security.html). There are two There are two separate encryption systems, one for gossip traffic and one for RPC.
separate systems, one for gossip traffic and one for RPC.
## Gossip Encryption ## Gossip Encryption
Enabling gossip encryption only requires that you set an encryption key when Enabling gossip encryption only requires that you set an encryption key when
starting the Consul agent. The key can be set by setting the `encrypt` parameter starting the Consul agent. The key can be set via the `encrypt` parameter: this
in a configuration file for the agent. The key must be 16-bytes that are base64 value of this setting is a configuration file containing the encryption key.
encoded. The easiest method to obtain a cryptographically suitable key is by
using `consul keygen`. The key must be 16-bytes, Base64 encoded. As a convenience, Consul contains the
`consul keygen` commmand to generate a cryptographically suitable key:
```text ```text
$ consul keygen $ consul keygen
cg8StVXbQJ0gPvMd9o7yrg== cg8StVXbQJ0gPvMd9o7yrg==
``` ```
With that key, you can enable encryption on the agent. You can verify With that key, you can enable encryption on the agent. If encryption is enabled,
encryption is enabled because the output will include "Encrypted: true". the output of `consul agent` will include "Encrypted: true":
```text ```text
$ cat encrypt.json $ cat encrypt.json
@ -53,28 +53,27 @@ order to send and receive cluster information.
# RPC Encryption with TLS # RPC Encryption with TLS
Consul supports using TLS to verify the authenticity of servers and clients. For this Consul supports using TLS to verify the authenticity of servers and clients. To enable this,
to work, Consul requires that all clients and servers have key pairs that are generated Consul requires that all clients and servers have key pairs that are generated by a single
by a single Certificate Authority. This can be a private CA, used only internally. The Certificate Authority. This can be a private CA, used only internally. The
CA then signs keys for each of the agents. [Here](https://langui.sh/2009/01/18/openssl-self-signed-ca/) CA then signs keys for each of the agents, as in
is a tutorial on generating both a CA and signing keys using OpenSSL. Client certificates [this tutorial on generationg both a CA and signing keys](https://langui.sh/2009/01/18/openssl-self-signed-ca/)
must have extended key usage enabled for client and server authentication. 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.
There are a number of things to consider when setting up TLS for Consul. Either we can When enabling TLS for Consul, we first must decide what we wish to verify. TLS can be used
use TLS just to verify the authenticity of the servers, or we can also verify the authenticity to verify the authenticity of the servers or also verify the authenticity of clients, controlled
of clients. The former can be used to prevent unauthorized access. This behavior is controlled by the `verify_incoming` or `verify_outgoing` [options](/docs/agent/options.html), respectively.
using either the `verify_incoming` and `verify_outgoing` [options](/docs/agent/options.html).
If `verify_outgoing` is set, then agents verify the authenticity of Consuls for outgoing If `verify_outgoing` is set, agents verify the authenticity of Consul for outgoing
connections. This means server nodes must present a certificate signed by the `ca_file` that connections. Server nodes must present a certificate signed by the `ca_file` setting that must
the agent has. This option must be set on all agents, and there must be a `ca_file` provided be present all agents. All server nodes must have an appropriate key pair set using `cert_file` and `key_file`.
to check the certificate against. If this is set, then all server nodes must have an appropriate
key pair set using `cert_file` and `key_file`.
If `verify_incoming` is set, then the servers verify the authenticity of all incoming If `verify_incoming` is set, then the servers verify the authenticity of all incoming
connections. Servers will also disallow any non-TLS connections. If this is set, then all connections. Servers will also disallow any non-TLS connections. All clients must have
clients must have a valid key pair set using `cert_file` and `key_file`. To force clients to a valid key pair set using `cert_file` and `key_file`. To force clients to use TLS,
use TLS, `verify_outgoing` must also be set. `verify_outgoing` must also be set.
TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP 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. and is secured using a symmetric key. See above for enabling gossip encryption.