From edeab6a0d2def544164196fec64d493d947d3430 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 18:33:29 -0500 Subject: [PATCH 1/6] Substantial and potentially inaccurate rewrite to docs/agent/encryption. --- .../docs/agent/encryption.html.markdown | 55 +++++++++---------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index 6de76cbe09..b51b230088 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -3,31 +3,31 @@ 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 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 The Consul agent supports encrypting all of its network traffic. The exact -method of this encryption is described on the -[encryption internals page](/docs/internals/security.html). There are two -separate systems, one for gossip traffic and one for RPC. +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. ## Gossip Encryption 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 -in a configuration file for the agent. The key must be 16-bytes that are base64 -encoded. The easiest method to obtain a cryptographically suitable key is by -using `consul keygen`. +starting the Consul agent. The key can be set via the `encrypt` parameter: this +value of this setting is a configuration file containing the encryption key. + +The key must be 16-bytes, Base64 encoded. As a convenience, Consul contains the +`consul keygen` commmand to generate a cryptographically suitable key: ```text $ consul keygen cg8StVXbQJ0gPvMd9o7yrg== ``` -With that key, you can enable encryption on the agent. You can verify -encryption is enabled because the output will include "Encrypted: true". +With that key, you can enable encryption on the agent. If encryption is enabled, +the output of `consul agent` will include "Encrypted: true": ```text $ cat encrypt.json @@ -53,28 +53,27 @@ order to send and receive cluster information. # RPC Encryption with TLS -Consul supports using TLS to verify the authenticity of servers and clients. For this -to work, 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. [Here](https://langui.sh/2009/01/18/openssl-self-signed-ca/) -is a tutorial on generating both a CA and signing keys using OpenSSL. Client certificates -must have extended key usage enabled for client and server authentication. +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 generationg 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. -There are a number of things to consider when setting up TLS for Consul. Either we can -use TLS just to verify the authenticity of the servers, or we can also verify the authenticity -of clients. The former can be used to prevent unauthorized access. This behavior is controlled -using either the `verify_incoming` and `verify_outgoing` [options](/docs/agent/options.html). +When enabling TLS for Consul, we first must decide what we wish to verify. TLS can be used +to verify the authenticity of the servers or also verify the authenticity of clients, controlled +by the `verify_incoming` or `verify_outgoing` [options](/docs/agent/options.html), respectively. -If `verify_outgoing` is set, then agents verify the authenticity of Consuls for outgoing -connections. This means server nodes must present a certificate signed by the `ca_file` that -the agent has. This option must be set on all agents, and there must be a `ca_file` provided -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_outgoing` is set, agents verify the authenticity of Consul for outgoing +connections. Server nodes must present a certificate signed by the `ca_file` setting that must +be present all agents. 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 -connections. Servers will also disallow any non-TLS connections. If this is set, then all -clients must have a valid key pair set using `cert_file` and `key_file`. To force clients to -use TLS, `verify_outgoing` must also be set. +connections. Servers will also disallow any non-TLS connections. All clients must have +a valid key pair set using `cert_file` and `key_file`. 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. From 26bbda57d0084e81970abb4fd6dbdc32bbbf987f Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 18:55:58 -0500 Subject: [PATCH 2/6] Tighten up TLS mode language a bit. --- website/source/docs/agent/encryption.html.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index b51b230088..7b978dd9f0 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -63,8 +63,8 @@ using OpenSSL. Note: client certificates must have for client and server authentication. When enabling TLS for Consul, we first must decide what we wish to verify. TLS can be used -to verify the authenticity of the servers or also verify the authenticity of clients, controlled -by the `verify_incoming` or `verify_outgoing` [options](/docs/agent/options.html), respectively. +to verify the authenticity of the servers or verify the authenticity of clients. These modes are +controlled by the `verify_incoming` and `verify_outgoing` [options](/docs/agent/options.html), respectively. If `verify_outgoing` is set, agents verify the authenticity of Consul for outgoing connections. Server nodes must present a certificate signed by the `ca_file` setting that must From 0cd1739ebcaa1cad39364cbfadef2f3947f13ff9 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 18:59:11 -0500 Subject: [PATCH 3/6] Tighten up TLS setting language a bit. --- website/source/docs/agent/encryption.html.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index 7b978dd9f0..3da1db8b0c 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -67,8 +67,8 @@ to verify the authenticity of the servers or verify the authenticity of clients. controlled by the `verify_incoming` and `verify_outgoing` [options](/docs/agent/options.html), respectively. If `verify_outgoing` is set, agents verify the authenticity of Consul for outgoing -connections. Server nodes must present a certificate signed by the `ca_file` setting that must -be present all agents. All server nodes must have an appropriate key pair set using `cert_file` and `key_file`. +connections. Server nodes must present a certificate signed by the `ca_file` setting that in turn must +be present on all agents. 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 connections. Servers will also disallow any non-TLS connections. All clients must have From b18b6491ffae25e43bbf3e930cc33737d64f5a3b Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 21:59:59 -0500 Subject: [PATCH 4/6] Final edits to encryption doc. --- website/source/docs/agent/encryption.html.markdown | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index 3da1db8b0c..2a363a216e 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -62,15 +62,15 @@ 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. -When enabling TLS for Consul, we first must decide what we wish to verify. TLS can be used -to verify the authenticity of the servers or verify the authenticity of clients. These modes are -controlled by the `verify_incoming` and `verify_outgoing` [options](/docs/agent/options.html), respectively. +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` and `verify_incoming` [options](/docs/agent/options.html), respectively. If `verify_outgoing` is set, agents verify the authenticity of Consul for outgoing -connections. Server nodes must present a certificate signed by the `ca_file` setting that in turn must -be present on all agents. All server nodes must have an appropriate key pair set using `cert_file` and `key_file`. +connections. Server nodes must present a certificate signed by the certificate authority +present on all agents, set via the agent's `ca_file` option. 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, the servers verify the authenticity of all incoming connections. Servers will also disallow any non-TLS connections. All clients must have a valid key pair set using `cert_file` and `key_file`. To force clients to use TLS, `verify_outgoing` must also be set. From 02c7ed0e94f75d45fc633f5e102f1d7b8e0e9ce4 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 22:01:33 -0500 Subject: [PATCH 5/6] Final edits to encryption doc. --- website/source/docs/agent/encryption.html.markdown | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index 2a363a216e..2ff2b0f6af 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -71,9 +71,8 @@ present on all agents, set via the agent's `ca_file` option. All server nodes mu appropriate key pair set using `cert_file` and `key_file`. If `verify_incoming` is set, the servers verify the authenticity of all incoming -connections. Servers will also disallow any non-TLS connections. All clients must have -a valid key pair set using `cert_file` and `key_file`. To force clients to use TLS, -`verify_outgoing` must also be set. +connections. All clients must have a valid key pair set using `cert_file` and `key_file`. 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. From 3a184a06f71e6600f3497397fd278dfd8e0bc10d Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 31 Jan 2015 22:05:00 -0500 Subject: [PATCH 6/6] Final edits to encryption doc. --- website/source/docs/agent/encryption.html.markdown | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/website/source/docs/agent/encryption.html.markdown b/website/source/docs/agent/encryption.html.markdown index 2ff2b0f6af..f13ae56470 100644 --- a/website/source/docs/agent/encryption.html.markdown +++ b/website/source/docs/agent/encryption.html.markdown @@ -15,10 +15,10 @@ There are two separate encryption systems, one for gossip traffic and one for RP ## Gossip Encryption 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: this +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. -The key must be 16-bytes, Base64 encoded. As a convenience, Consul contains the +The key must be 16-bytes, Base64 encoded. As a convenience, Consul provides the `consul keygen` commmand to generate a cryptographically suitable key: ```text @@ -57,13 +57,14 @@ Consul supports using TLS to verify the authenticity of servers and clients. To 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 generationg both a CA and signing keys](https://langui.sh/2009/01/18/openssl-self-signed-ca/) +[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. -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` and `verify_incoming` [options](/docs/agent/options.html), respectively. +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` and `verify_incoming` [options](/docs/agent/options.html), +respectively. If `verify_outgoing` is set, agents verify the authenticity of Consul for outgoing connections. Server nodes must present a certificate signed by the certificate authority