From dfedb5a97fd1eb4b904709c1c74470dc22b3842c Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 8 Jul 2021 17:07:15 -0400 Subject: [PATCH] contrib: add description of cert relationship diagram And links to code --- docs/service-mesh/ca/README.md | 40 +++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md index a9c7aaa4d..39f7f6ecf 100644 --- a/docs/service-mesh/ca/README.md +++ b/docs/service-mesh/ca/README.md @@ -3,6 +3,17 @@ The Certificate Authority subsystem manages a CA trust chain for issuing certificates to services and client agents (via auto-encrypt and auto-config). +The code for the Certificate Authority is in the following packages: +1. most of the core logic is in [agent/consul/leader_connect_ca.go] +2. the providers are in [agent/connect/ca] +3. the RPC interface is in [agent/consul/connect_ca_endpoint.go] + + +[agent/consul/leader_connect_ca.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/leader_connect_ca.go +[agent/connect/ca]: https://github.com/hashicorp/consul/blob/main/agent/connect/ca/ +[agent/consul/connect_ca_endpoint.go]: https://github.com/hashicorp/consul/blob/main/agent/consul/connect_ca_endpoint.go + + ## Architecture ### High level overview @@ -10,6 +21,7 @@ services and client agents (via auto-encrypt and auto-config). In Consul the leader is responsible for handling of the CA management. When a leader election happen, and the elected leader do not have any root CA available it will start a process of creating a set of CA certificate. Those certificates will use to authenticate/encrypt communication between services (service mesh) or between `Consul client agent` (auto-encrypt/auto-config). This process is described in the following diagram: + ![CA creation](./hl-ca-overview.svg) [source](./hl-ca-overview.mmd) @@ -28,17 +40,25 @@ secondary. [source](./cert-relationship.mmd) -TODO: describe the relationship -* what does it mean for the external root CA to be optional - * it always exists , unless the Consul CA provider is used AND it has generated the CA - root. -* relationship between Primary Root CA and Signing CA in the primary - * sometimes its the same thing (Consul, and AWS providers) - * sometimes it is different (Vault provider) -* client agent cert is used by auto-encrypt for Agent HTTP TLS (and client side of RPC - TLS) -* leaf cert service is the cert used by a service in the mesh +In most cases there is an external root CA that provides an intermediate CA that Consul +uses as the Primary Root CA. The only except to this is when the Consul CA Provider is +used without specifying a `RootCert`. In this one case Consul will generate the the Root CA +from the provided primary key, and it will be used in the primary as the top of the chain +of trust. + +In the primary datacenter, the Consul and AWS providers use the Primary Root CA to sign +leaf certificates. The Vault provider uses an intermediate CA to sign leaf certificates. + +Leaf certificates are created for two purposes: +1. the Leaf Cert Service is used by envoy proxies in the mesh to perform mTLS with other + services. +2. the Leaf Cert Client Agent is created by auto-encrypt and auto-config. It is used by + client agents for HTTP API TLS, and for mTLS for RPC requests to servers. + +Any secondary datacenters receive an intermediate certificate, signed by the Primary Root +CA, which is used as the CA certificate to sign leaf certificates in the secondary +datacenter. ### detailed call flow - sequence diagram for leader election