github.com/outbrain/consul@v1.4.5/website/source/docs/agent/encryption.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Encryption"
     4  sidebar_current: "docs-agent-encryption"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Encryption
    10  
    11  The Consul agent supports encrypting all of its network traffic. The exact
    12  method of encryption is described on the [encryption internals page](/docs/internals/security.html).
    13  There are two separate encryption systems, one for gossip traffic and one for RPC.
    14  If you are configuring encryption, review this [guide](/docs/guides/agent-encryption.html).
    15  
    16  ## Gossip Encryption
    17  
    18  Enabling gossip encryption only requires that you set an encryption key when
    19  starting the Consul agent. The key can be set via the `encrypt` parameter.
    20  
    21  ~> **WAN Joined Datacenters Note:** If using multiple WAN joined datacenters, be sure to use _the same encryption key_ in all datacenters.
    22  
    23  The key must be 16-bytes, Base64 encoded. As a convenience, Consul provides the
    24  [`consul keygen`](/docs/commands/keygen.html) command to generate a
    25  cryptographically suitable key:
    26  
    27  ```text
    28  $ consul keygen
    29  cg8StVXbQJ0gPvMd9o7yrg==
    30  ```
    31  
    32  With that key, you can enable encryption on the agent. If encryption is enabled,
    33  the output of [`consul agent`](/docs/commands/agent.html) will include "Encrypt: true":
    34  
    35  ```text
    36  $ cat encrypt.json
    37  {"encrypt": "cg8StVXbQJ0gPvMd9o7yrg=="}
    38  
    39  $ consul agent -data-dir=/tmp/consul -config-file=encrypt.json
    40  ==> WARNING: LAN keyring exists but -encrypt given, using keyring
    41  ==> WARNING: WAN keyring exists but -encrypt given, using keyring
    42  ==> Starting Consul agent...
    43  ==> Starting Consul agent RPC...
    44  ==> Consul agent running!
    45           Node name: 'Armons-MacBook-Air.local'
    46          Datacenter: 'dc1'
    47              Server: false (bootstrap: false)
    48         Client Addr: 127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, RPC: 8400)
    49        Cluster Addr: 10.1.10.12 (LAN: 8301, WAN: 8302)
    50      Gossip encrypt: true, RPC-TLS: false, TLS-Incoming: false
    51  ...
    52  ```
    53  
    54  All nodes within a Consul cluster must share the same encryption key in
    55  order to send and receive cluster information.
    56  
    57  ## Configuring Gossip Encryption on an existing cluster
    58  
    59  As of version 0.8.4, Consul supports upshifting to encrypted gossip on a running cluster
    60  through the following process. Review this [step-by-step guide](/docs/guides/agent-encryption.html#enable-gossip-encryption-existing-cluster) 
    61  to encrypt gossip on an existing cluster.
    62  
    63  ## RPC Encryption with TLS
    64  
    65  Consul supports using TLS to verify the authenticity of servers and clients. To enable this,
    66  Consul requires that all clients and servers have key pairs that are generated by a single
    67  Certificate Authority. This can be a private CA, used only internally. The
    68  CA then signs keys for each of the agents, as in
    69  [this tutorial on generating both a CA and signing keys](/docs/guides/creating-certificates.html). 
    70  
    71  TLS can be used to verify the authenticity of the servers or verify the authenticity of clients.
    72  These modes are controlled by the [`verify_outgoing`](/docs/agent/options.html#verify_outgoing),
    73  [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname),
    74  and [`verify_incoming`](/docs/agent/options.html#verify_incoming) options, respectively.
    75  
    76  If [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) is set, agents verify the
    77  authenticity of Consul for outgoing connections. Server nodes must present a certificate signed
    78  by a common certificate authority present on all agents, set via the agent's
    79  [`ca_file`](/docs/agent/options.html#ca_file) and [`ca_path`](/docs/agent/options.html#ca_path)
    80  options. All server nodes must have an appropriate key pair set using [`cert_file`]
    81  (/docs/agent/options.html#cert_file) and [`key_file`](/docs/agent/options.html#key_file).
    82  
    83  If [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname) is set, then
    84  outgoing connections perform hostname verification. All servers must have a certificate
    85  valid for `server.<datacenter>.<domain>` or the client will reject the handshake. This is
    86  a new configuration as of 0.5.1, and it is used to prevent a compromised client from being
    87  able to restart in server mode and perform a MITM (Man-In-The-Middle) attack. New deployments should set this
    88  to true, and generate the proper certificates, but this is defaulted to false to avoid breaking
    89  existing deployments.
    90  
    91  If [`verify_incoming`](/docs/agent/options.html#verify_incoming) is set, the servers verify the
    92  authenticity of all incoming connections. All clients must have a valid key pair set using
    93  [`cert_file`](/docs/agent/options.html#cert_file) and
    94  [`key_file`](/docs/agent/options.html#key_file). Servers will
    95  also disallow any non-TLS connections. To force clients to use TLS,
    96  [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) must also be set.
    97  
    98  TLS is used to secure the RPC calls between agents, but gossip between nodes is done over UDP
    99  and is secured using a symmetric key. See above for enabling gossip encryption.
   100  
   101  ## Configuring TLS on an existing cluster
   102  
   103  As of version 0.8.4, Consul supports migrating to TLS-encrypted traffic on a running cluster
   104  without downtime. This process assumes a starting point with no TLS settings configured, and involves
   105  an intermediate step in order to get to full TLS encryption. Review this step-by-step
   106  [guide](/docs/guides/agent-encryption.html#enable-tls-existing-cluster) to learn how. 
   107