-
Notifications
You must be signed in to change notification settings - Fork 4.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
CE-654 - TLS Encryption docs + CE-713 - Gossip Encryption key rotation #21509
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking great so far. The only page I still need to review is the encryption/mtls
page.
The Consul agent supports encryption for all of its network traffic. There are two separate encryption systems, one for gossip | ||
traffic and one for HTTP + RPC. The [Encryption](/consul/docs/security/encryption) section describes the logic behind these two different encryption systems and provides configuration guidance for them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Consul agent supports encryption for all of its network traffic. There are two separate encryption systems, one for gossip | |
traffic and one for HTTP + RPC. The [Encryption](/consul/docs/security/encryption) section describes the logic behind these two different encryption systems and provides configuration guidance for them. | |
The Consul agent supports encryption for all of its network traffic. There are two separate encryption systems: | |
- A gossip encryption system | |
- An mTLS encryption system for HTTP and RPC | |
For more information about these two different encryption systems, as well as configuration guidance, refer to [Consul encryption](/consul/docs/security/encryption). |
I think the unordered list is appropriate here to help emphasize the two encryption systems.
Consul supports encrypting all of its network traffic. Remote Procedure Calls (RPCs) between client and server agents can be encrypted with TLS and authenticated with certificates. Gossip communication between all agents can also be encrypted. | ||
--- | ||
|
||
# Encryption |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Match page title after responding to suggestion.
This topic describes the two different encryption systems available in Consul to secure network traffic, Gossip encryption and mTLS. | ||
|
||
[Consul security model](/consul/docs/security/security-models/core) defines the guidelines for operating a secure Consul deployment. Its recommendations are applicable only if all parts of the system are running with a secure configuration. | ||
|
||
[Gossip Encryption](/consul/docs/security/encryption#gossip-encryption) and [Mutual TLS Encryption](/consul/docs/security/encryption#mutual-tls-mtls-encryption) are the foundations for a secure Consul datacenter. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This topic describes the two different encryption systems available in Consul to secure network traffic, Gossip encryption and mTLS. | |
[Consul security model](/consul/docs/security/security-models/core) defines the guidelines for operating a secure Consul deployment. Its recommendations are applicable only if all parts of the system are running with a secure configuration. | |
[Gossip Encryption](/consul/docs/security/encryption#gossip-encryption) and [Mutual TLS Encryption](/consul/docs/security/encryption#mutual-tls-mtls-encryption) are the foundations for a secure Consul datacenter. | |
This topic provides an overview of the two distinct encryption systems available in Consul. [Gossip encryption](/consul/docs/security/encryption#gossip-encryption) and [Mutual TLS encryption](/consul/docs/security/encryption#mutual-tls-mtls-encryption) are the foundations of a secure Consul datacenter. | |
The guidelines in the [Consul security model](/consul/docs/security/security-models/core) for operating a secure Consul deployment recommends using both encryption systems. |
Re-orders sentences to avoid the jump back and forth between the security model and the encryption systems
|
||
## Gossip Encryption | ||
|
||
Consul uses a [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol) to manage membership and broadcast messages to the cluster. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Consul uses a [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol) to manage membership and broadcast messages to the cluster. | |
Consul uses a [gossip protocol](/consul/docs/architecture/gossip) to perform the following cluster operations: |
|
||
### Promote the new key to primary | ||
|
||
Once all agents have received the key and are able to use it as the primary encryption key, it is possible to promote the new key to primary. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Once all agents have received the key and are able to use it as the primary encryption key, it is possible to promote the new key to primary. | |
After all agents recognize the key, it is possible to promote it to be the new primary encryption key. |
|
||
### Remove the old key from the keyring | ||
|
||
To avoid unused keys remaining in the keyring, we recommended you remove the old primary from the keyring once a new key is installed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To avoid unused keys remaining in the keyring, we recommended you remove the old primary from the keyring once a new key is installed. | |
Unused keys in the keyring are a potential security risk to your Consul cluster. We recommended that you remove the former primary key from the keyring after a new key is installed. |
Documentation for the commands used in this topic is available at [Consul agent configuration - Encryption Parameters](/consul/docs/agent/config/config-files#encryption-parameters). You can find more information over the gossip protocol used by Consul at [Gossip Protocol](/consul/docs/architecture/gossip). | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Documentation for the commands used in this topic is available at [Consul agent configuration - Encryption Parameters](/consul/docs/agent/config/config-files#encryption-parameters). You can find more information over the gossip protocol used by Consul at [Gossip Protocol](/consul/docs/architecture/gossip). |
Not really "next steps" - I suggest removing this sentence.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see your point but I think is always useful to have a place where some links to the documentation/reference for the commands shown is located.
|
||
Documentation for the commands used in this topic is available at [Consul agent configuration - Encryption Parameters](/consul/docs/agent/config/config-files#encryption-parameters). You can find more information over the gossip protocol used by Consul at [Gossip Protocol](/consul/docs/architecture/gossip). | ||
|
||
After enabling gossip encryption, to continue securing your Consul datacenter, enable mutual TLS encryption. Read more on [Mutual TLS (mTLS) Encryption](/consul/docs/security/encryption/mtls). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After enabling gossip encryption, to continue securing your Consul datacenter, enable mutual TLS encryption. Read more on [Mutual TLS (mTLS) Encryption](/consul/docs/security/encryption/mtls). | |
After you enable gossip encryption, you can continue to process to secure your Consul datacenter by enabling mutual TLS encryption. For more information, refer to [Mutual TLS (mTLS) Encryption](/consul/docs/security/encryption/mtls). |
|
||
After enabling gossip encryption, to continue securing your Consul datacenter, enable mutual TLS encryption. Read more on [Mutual TLS (mTLS) Encryption](/consul/docs/security/encryption/mtls). | ||
|
||
To learn how to automate gossip key rotation using HashiCorp Vault and consul-template, refer to the [Automatically Rotate Gossip Encryption Keys Secured in Vault](/consul/tutorials/operate-consul/vault-kv-consul-secure-gossip) tutorial. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To learn how to automate gossip key rotation using HashiCorp Vault and consul-template, refer to the [Automatically Rotate Gossip Encryption Keys Secured in Vault](/consul/tutorials/operate-consul/vault-kv-consul-secure-gossip) tutorial. | |
To learn how to automate gossip key rotation using HashiCorp Vault and consul-template, refer to the [Automatically Rotate Gossip Encryption Keys Secured in Vault tutorial](/consul/tutorials/operate-consul/vault-kv-consul-secure-gossip). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestions for the mTLS page to complete my review.
layout: docs | ||
page_title: mTLS Encryption | ||
description: >- | ||
Consul supports encrypting all of its network traffic. Remote Process Calls (RPCs) between client and server agents can be encrypted with TLS and authenticated with certificates. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Consul supports encrypting all of its network traffic. Remote Process Calls (RPCs) between client and server agents can be encrypted with TLS and authenticated with certificates. | |
Consul supports encrypting all of its network traffic. Learn how to encrypt and authenticate Remote Process Calls (RPCs) between client and server agents with TLS certificates. |
This topics describes how to enable Mutual TLS (mTLS) encryption on a Consul datacenter. | ||
|
||
The content in this page is not referred to Consul service mesh mTLS encryption. For documentation about Consul service mesh Certification authority refer to [Service Mesh Certificate Authority](/consul/docs/connect/ca) documentation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This topics describes how to enable Mutual TLS (mTLS) encryption on a Consul datacenter. | |
The content in this page is not referred to Consul service mesh mTLS encryption. For documentation about Consul service mesh Certification authority refer to [Service Mesh Certificate Authority](/consul/docs/connect/ca) documentation. | |
This topic describes mutual TLS (mTLS) encryption between agents in a Consul datacenter. | |
This mTLS encryption is distinct from Consul service mesh mTLS encryption. To learn about encrypted mTLS communication between services, refer to [service mesh certificate authority](/consul/docs/connect/ca). |
|
||
## Benefits of TLS encryption | ||
|
||
Consul supports the use of TLS certificates to secure the traffic related to the `RCP`, `gRPC`, and `HTTP` communications and to verify the authenticity of servers and clients. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Consul supports the use of TLS certificates to secure the traffic related to the `RCP`, `gRPC`, and `HTTP` communications and to verify the authenticity of servers and clients. | |
Consul supports TLS certificates that verify the authenticity of servers and clients to secure `RCP`, `gRPC`, and `HTTP` traffic. |
Simplifying sentence
|
||
### Interact with Consul without a client certificate | ||
|
||
If you want to avoid the need to present a valid client certificate every time you need to interact with Consul API, CLI, or UI, it is possible to configure Consul to trust all incoming HTTPs connections. Setting `tls.https.verify_incoming` to `false` removes the need to present a client certificate. RCP communications are still mTLS encrypted. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you want to avoid the need to present a valid client certificate every time you need to interact with Consul API, CLI, or UI, it is possible to configure Consul to trust all incoming HTTPs connections. Setting `tls.https.verify_incoming` to `false` removes the need to present a client certificate. RCP communications are still mTLS encrypted. | |
If you want to avoid the need to present a valid client certificate every time you interact with Consul using the HTTP API, CLI, or UI, configure Consul to trust all incoming HTTPS connections by seting `tls.https.verify_incoming` to `false`. RPC communications are still mTLS encrypted. |
|
||
### Use HTTP for local client interaction | ||
|
||
If you want to avoid the need to present a valid client certificate or to use the CA certificate every time you need to interact with your local Consul agent, it is possible to configure Consul to keep the HTTP listener only active on the `localhost` interface. External requests to the API or the UI will still be TLS protected but setting `tls.https.verify_incoming` to `false` removes the need to present a client certificate. RCP communications are still mTLS encrypted. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you want to avoid the need to present a valid client certificate or to use the CA certificate every time you need to interact with your local Consul agent, it is possible to configure Consul to keep the HTTP listener only active on the `localhost` interface. External requests to the API or the UI will still be TLS protected but setting `tls.https.verify_incoming` to `false` removes the need to present a client certificate. RCP communications are still mTLS encrypted. | |
If you want to avoid the need to present a valid client certificate or to use the CA certificate every time you interact with the local Consul agent, configure Consul to keep the HTTP listener active on the `localhost` interface only and set `tls.https.verify_incoming` to `false`. External requests to the API or UI are still protected by TLS encryption, requests that originate locally do not need to present a client certificate. RPC communications are still mTLS encrypted. |
After completing the steps in this topic, your agents will be configured with TLS for encrypted communication. With the auto encryption method, your | ||
client certificates are managed by the server. With the operator method, you distributed all the certificates, but have a more flexible configuration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After completing the steps in this topic, your agents will be configured with TLS for encrypted communication. With the auto encryption method, your | |
client certificates are managed by the server. With the operator method, you distributed all the certificates, but have a more flexible configuration. | |
Your agents are now configured with mTLS for encrypted communication. With the auto encryption method, your | |
client certificates are managed by the server. With the operator method, you distributed all the certificates manually, but have a more flexible configuration. |
After completing the steps in this topic, your agents will be configured with TLS for encrypted communication. With the auto encryption method, your | ||
client certificates are managed by the server. With the operator method, you distributed all the certificates, but have a more flexible configuration. | ||
|
||
Documentation for the commands used in this topic is available at [Consul agent configuration - TLS configuration reference](/consul/docs/agent/config/config-files#tls-configuration-reference) documentation and at the [`consul tls` CLI command reference](/consul/commands/tls). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Documentation for the commands used in this topic is available at [Consul agent configuration - TLS configuration reference](/consul/docs/agent/config/config-files#tls-configuration-reference) documentation and at the [`consul tls` CLI command reference](/consul/commands/tls). | |
Documentation for the commands used in this topic is available at [Consul agent configuration - TLS configuration reference](/consul/docs/agent/config/config-files#tls-configuration-reference) and the [`consul tls` CLI command reference](/consul/commands/tls). |
|
||
To learn how to automate TLS certificate generation and rotation, refer to the [Generate mTLS Certificates for Consul with Vault](/consul/tutorials/operate-consul/vault-pki-consul-secure-tls) tutorial. | ||
|
||
The other prerequisites for a secure Consul deployment are [gossip encryption](/consul/docs/security/encryption/gossip) and [Access Control Lists (ACLs)](/consul/docs/security/acl) with default deny policy. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The other prerequisites for a secure Consul deployment are [gossip encryption](/consul/docs/security/encryption/gossip) and [Access Control Lists (ACLs)](/consul/docs/security/acl) with default deny policy. | |
To continue securing your Consul deployment, add [gossip encryption](/consul/docs/security/encryption/gossip) and enable [Access Control Lists (ACLs)](/consul/docs/security/acl) with the default deny policy. |
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Absolutely fabulous work.
Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
#21509) * New proposed structure * Fix structure and add some content * Fix structure and add some content * Fix structure and add some content * Add content * Add content * mtls steps * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * spacing fixes * Replace <CodeTabs> * <CodeBlockConfig> alignment * indent fixes * spacing * More Code tabs fixes * Structure chenges * Structure chenges * Extra content and CE-713 migration * Extra content * Extra content * Extra content * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Apply suggestions from code review * Test CodeTabs * Test CodeTabs * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: boruszak <jeffrey.boruszak@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
CE-654 - TLS Encryption docs + CE-713 - Gossip Encryption key rotation (#21509) * New proposed structure * Fix structure and add some content * Fix structure and add some content * Fix structure and add some content * Add content * Add content * mtls steps * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * Encryption docs structure change * spacing fixes * Replace <CodeTabs> * <CodeBlockConfig> alignment * indent fixes * spacing * More Code tabs fixes * Structure chenges * Structure chenges * Extra content and CE-713 migration * Extra content * Extra content * Extra content * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review * Test CodeTabs * Test CodeTabs * Apply suggestions from code review --------- Co-authored-by: danielehc <40759828+danielehc@users.noreply.github.com>
Jira tickets reference
Description
encryption
section.🎪 Preview