From 79f4d53079a63d29a29464850da1635864270163 Mon Sep 17 00:00:00 2001
From: Daniel Nephin <dnephin@hashicorp.com>
Date: Thu, 8 Jul 2021 14:52:22 -0400
Subject: [PATCH] contrib: add first draft of Connect CA developer docs

Co-authored-by: Dhia Ayachi <dhia@hashicorp.com>
---
 docs/service-mesh/README.md                |  2 +-
 docs/service-mesh/ca/README.md             | 40 ++++++++++++++++++++++
 docs/service-mesh/ca/cert-relationship.mmd | 31 +++++++++++++++++
 docs/service-mesh/ca/cert-relationship.svg |  1 +
 4 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/service-mesh/ca/README.md
 create mode 100644 docs/service-mesh/ca/cert-relationship.mmd
 create mode 100644 docs/service-mesh/ca/cert-relationship.svg

diff --git a/docs/service-mesh/README.md b/docs/service-mesh/README.md
index 7bc16f7f77..470fd28f29 100644
--- a/docs/service-mesh/README.md
+++ b/docs/service-mesh/README.md
@@ -3,7 +3,7 @@
 - call out: envoy/proxy is the data plane, Consul is the control plane
 - [xDS Server] - a gRPC service that implements [xDS] and handles requests from an [envoy proxy].
 - [agent/proxycfg]
-- CA Manager - certificate authority
+- [Certificate Authority](./ca) for issuing TLS certs for services and client agents
 - command/connect/envoy - bootstrapping and running envoy
 - command/connect/proxy - built-in proxy that is dev-only and not supported 
   for production.
diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md
new file mode 100644
index 0000000000..7a12921772
--- /dev/null
+++ b/docs/service-mesh/ca/README.md
@@ -0,0 +1,40 @@
+# Certificate Authority (Connect CA)
+
+The Certificate Authority subsystem manages a CA trust chain for issuing certificates to
+services and client agents (via auto-encrypt and auto-config).
+
+## Architecture
+
+### High level overview
+
+- we can start with the mind map
+- high level explaination of what are the features that are involved in CA (mesh/connect, auto encrypt)
+- add all the func that are involved in the CA operations
+- relationship between the different certs
+
+
+### CA and Certificate relationship
+
+This diagram shows the relationship between the CA certificates in Consul primary and
+secondary.
+
+![CA relationship](./cert-relationship.svg)
+
+<sup>[source](./cert-relationship.mmd)</sup>
+
+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
+
+### detailed call flow
+- sequence diagram for leader election
+- sequence diagram for leaf signing
+- sequence diagram for CA cert rotation
diff --git a/docs/service-mesh/ca/cert-relationship.mmd b/docs/service-mesh/ca/cert-relationship.mmd
new file mode 100644
index 0000000000..85ae848dcb
--- /dev/null
+++ b/docs/service-mesh/ca/cert-relationship.mmd
@@ -0,0 +1,31 @@
+graph TD
+ 
+    ExternalRootCA["External RootCA (optional)"]
+
+    subgraph "Consul Primary"
+        PrimaryRootCA["Primary Root CA"]
+        PrimarySigningCA["Primary Signing CA (conditional)"]
+    end
+
+    subgraph "Consul Secondary"
+        SeconarySigningCA["Seconary Signing CA"]
+    end
+
+    LeafCertAgentPrimary[Leaf Cert Client Agent]
+    LeafCertServicePrimary[Leaf Cert Service]
+
+    LeafCertAgentSecondary[Leaf Cert Client Agent]
+    LeafCertServiceSecondary[Leaf Cert Service]
+
+
+    ExternalRootCA -.-> PrimaryRootCA
+    PrimaryRootCA -.-> PrimarySigningCA
+
+    PrimaryRootCA --> SeconarySigningCA
+
+    PrimarySigningCA --> LeafCertAgentPrimary
+    PrimarySigningCA --> LeafCertServicePrimary
+
+    SeconarySigningCA --> LeafCertAgentSecondary
+    SeconarySigningCA --> LeafCertServiceSecondary
+
diff --git a/docs/service-mesh/ca/cert-relationship.svg b/docs/service-mesh/ca/cert-relationship.svg
new file mode 100644
index 0000000000..a32f838d19
--- /dev/null
+++ b/docs/service-mesh/ca/cert-relationship.svg
@@ -0,0 +1 @@
+<svg id="graph-div" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" height="417" style="max-width: 827.58984375px;" viewBox="0 0 827.58984375 417"><style>#graph-div{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#graph-div .error-icon{fill:#552222;}#graph-div .error-text{fill:#552222;stroke:#552222;}#graph-div .edge-thickness-normal{stroke-width:2px;}#graph-div .edge-thickness-thick{stroke-width:3.5px;}#graph-div .edge-pattern-solid{stroke-dasharray:0;}#graph-div .edge-pattern-dashed{stroke-dasharray:3;}#graph-div .edge-pattern-dotted{stroke-dasharray:2;}#graph-div .marker{fill:#333333;stroke:#333333;}#graph-div .marker.cross{stroke:#333333;}#graph-div svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#graph-div .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#graph-div .cluster-label text{fill:#333;}#graph-div .cluster-label span{color:#333;}#graph-div .label text,#graph-div span{fill:#333;color:#333;}#graph-div .node rect,#graph-div .node circle,#graph-div .node ellipse,#graph-div .node polygon,#graph-div .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#graph-div .node .label{text-align:center;}#graph-div .node.clickable{cursor:pointer;}#graph-div .arrowheadPath{fill:#333333;}#graph-div .edgePath .path{stroke:#333333;stroke-width:1.5px;}#graph-div .flowchart-link{stroke:#333333;fill:none;}#graph-div .edgeLabel{background-color:#e8e8e8;text-align:center;}#graph-div .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#graph-div .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#graph-div .cluster text{fill:#333;}#graph-div .cluster span{color:#333;}#graph-div div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80,100%,96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#graph-div .node rect,#graph-div .er.entityBox{fill:rgb(220,71,125);stroke-width:1;stroke:black;}#graph-div .node .label{color:white;}#graph-div .cluster rect{fill:#f0f0f0;stroke-width:1px;stroke:#333;}#graph-div .edgeLabel{background-color:#f0f0f0;}#graph-div .er.entityBox + .er.entityLabel{fill:white;}#graph-div .er.attributeBoxEven,#graph-div .er.attributeBoxOdd{fill:#fff;stroke:#777;}#graph-div:root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}</style><g><g class="output"><g class="clusters"><g class="cluster" id="flowchart-subGraph1-7796" transform="translate(636.9765625,268)" style="opacity: 1;"><rect width="358.484375" height="94" x="-179.2421875" y="-47"></rect><g class="label" transform="translate(0, -33)" id="graph-divText"><g transform="translate(-62.3828125,-12)"><foreignObject width="124.765625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul Secondary</div></foreignObject></g></g></g><g class="cluster" id="flowchart-subGraph0-7797" transform="translate(209.046875,208.5)" style="opacity: 1;"><rect width="402.09375" height="213" x="-201.046875" y="-106.5"></rect><g class="label" transform="translate(0, -92.5)" id="graph-divText"><g transform="translate(-53.203125,-12)"><foreignObject width="106.40625" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Consul Primary</div></foreignObject></g></g></g></g><g class="edgePaths"><g class="edgePath LS-ExternalRootCA LE-PrimaryRootCA" id="L-ExternalRootCA-PrimaryRootCA" style="opacity: 1;"><path class="path" d="M224.046875,52L224.046875,56.166666666666664C224.046875,60.333333333333336,224.046875,68.66666666666667,224.046875,77C224.046875,85.33333333333333,224.046875,93.66666666666667,224.046875,102C224.046875,110.33333333333333,224.046875,118.66666666666667,224.046875,122.83333333333333L224.046875,127" marker-end="url(#arrowhead5097)" style="fill:none;stroke-width:2px;stroke-dasharray:3;"></path><defs><marker id="arrowhead5097" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimaryRootCA LE-PrimarySigningCA" id="L-PrimaryRootCA-PrimarySigningCA" style="opacity: 1;"><path class="path" d="M219.36602393617022,171L218.47949911347519,175.16666666666666C217.59297429078015,179.33333333333334,215.81992464539007,187.66666666666666,214.93339982269504,196C214.046875,204.33333333333334,214.046875,212.66666666666666,214.046875,221C214.046875,229.33333333333334,214.046875,237.66666666666666,214.046875,241.83333333333334L214.046875,246" marker-end="url(#arrowhead5098)" style="fill:none;stroke-width:2px;stroke-dasharray:3;"></path><defs><marker id="arrowhead5098" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimaryRootCA LE-SeconarySigningCA" id="L-PrimaryRootCA-SeconarySigningCA" style="opacity: 1;"><path class="path" d="M273.6364694148936,171L283.028438054078,175.16666666666666C292.4204066932624,179.33333333333334,311.2043439716312,187.66666666666666,320.5963126108156,196C329.98828125,204.33333333333334,329.98828125,212.66666666666666,368.3860677083333,222.61783253410795C406.7838541666667,232.56899840154918,483.5794270833333,244.1379968030984,521.9772135416666,249.922496003873L560.375,255.7069952046476" marker-end="url(#arrowhead5099)" style="fill:none"></path><defs><marker id="arrowhead5099" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimarySigningCA LE-LeafCertAgentPrimary" id="L-PrimarySigningCA-LeafCertAgentPrimary" style="opacity: 1;"><path class="path" d="M164.4572805851064,290L155.065311945922,294.1666666666667C145.6733433067376,298.3333333333333,126.8894060283688,306.6666666666667,117.49743738918441,315C108.10546875,323.3333333333333,108.10546875,331.6666666666667,108.10546875,340C108.10546875,348.3333333333333,108.10546875,356.6666666666667,108.10546875,360.8333333333333L108.10546875,365" marker-end="url(#arrowhead5100)" style="fill:none"></path><defs><marker id="arrowhead5100" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-PrimarySigningCA LE-LeafCertServicePrimary" id="L-PrimarySigningCA-LeafCertServicePrimary" style="opacity: 1;"><path class="path" d="M263.6364694148936,290L273.028438054078,294.1666666666667C282.4204066932624,298.3333333333333,301.2043439716312,306.6666666666667,310.5963126108156,315C319.98828125,323.3333333333333,319.98828125,331.6666666666667,319.98828125,340C319.98828125,348.3333333333333,319.98828125,356.6666666666667,319.98828125,360.8333333333333L319.98828125,365" marker-end="url(#arrowhead5101)" style="fill:none"></path><defs><marker id="arrowhead5101" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-SeconarySigningCA LE-LeafCertAgentSecondary" id="L-SeconarySigningCA-LeafCertAgentSecondary" style="opacity: 1;"><path class="path" d="M592.3869680851063,290L582.994999445922,294.1666666666667C573.6030308067376,298.3333333333333,554.8190935283687,306.6666666666667,545.4271248891844,315C536.03515625,323.3333333333333,536.03515625,331.6666666666667,536.03515625,340C536.03515625,348.3333333333333,536.03515625,356.6666666666667,536.03515625,360.8333333333333L536.03515625,365" marker-end="url(#arrowhead5102)" style="fill:none"></path><defs><marker id="arrowhead5102" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g><g class="edgePath LS-SeconarySigningCA LE-LeafCertServiceSecondary" id="L-SeconarySigningCA-LeafCertServiceSecondary" style="opacity: 1;"><path class="path" d="M691.5661569148937,290L700.958125554078,294.1666666666667C710.3500941932625,298.3333333333333,729.1340314716313,306.6666666666667,738.5260001108157,315C747.91796875,323.3333333333333,747.91796875,331.6666666666667,747.91796875,340C747.91796875,348.3333333333333,747.91796875,356.6666666666667,747.91796875,360.8333333333333L747.91796875,365" marker-end="url(#arrowhead5103)" style="fill:none"></path><defs><marker id="arrowhead5103" viewBox="0 0 10 10" refX="9" refY="5" markerUnits="strokeWidth" markerWidth="8" markerHeight="6" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowheadPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker></defs></g></g><g class="edgeLabels"><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-ExternalRootCA-PrimaryRootCA" class="edgeLabel L-LS-ExternalRootCA' L-LE-PrimaryRootCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimaryRootCA-PrimarySigningCA" class="edgeLabel L-LS-PrimaryRootCA' L-LE-PrimarySigningCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimaryRootCA-SeconarySigningCA" class="edgeLabel L-LS-PrimaryRootCA' L-LE-SeconarySigningCA"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimarySigningCA-LeafCertAgentPrimary" class="edgeLabel L-LS-PrimarySigningCA' L-LE-LeafCertAgentPrimary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-PrimarySigningCA-LeafCertServicePrimary" class="edgeLabel L-LS-PrimarySigningCA' L-LE-LeafCertServicePrimary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-SeconarySigningCA-LeafCertAgentSecondary" class="edgeLabel L-LS-SeconarySigningCA' L-LE-LeafCertAgentSecondary"></span></div></foreignObject></g></g><g class="edgeLabel" transform="" style="opacity: 1;"><g transform="translate(0,0)" class="label"><rect rx="0" ry="0" width="0" height="0"></rect><foreignObject width="0" height="0"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;"><span id="L-L-SeconarySigningCA-LeafCertServiceSecondary" class="edgeLabel L-LS-SeconarySigningCA' L-LE-LeafCertServiceSecondary"></span></div></foreignObject></g></g></g><g class="nodes"><g class="node default" id="flowchart-SeconarySigningCA-7777" transform="translate(641.9765625,268)" style="opacity: 1;"><rect rx="0" ry="0" x="-81.6015625" y="-22" width="163.203125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-71.6015625,-12)"><foreignObject width="143.203125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Seconary Signing CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-PrimaryRootCA-7775" transform="translate(224.046875,149)" style="opacity: 1;"><rect rx="0" ry="0" x="-67.7890625" y="-22" width="135.578125" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-57.7890625,-12)"><foreignObject width="115.578125" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Primary Root CA</div></foreignObject></g></g></g><g class="node default" id="flowchart-PrimarySigningCA-7776" transform="translate(214.046875,268)" style="opacity: 1;"><rect rx="0" ry="0" x="-125.2109375" y="-22" width="250.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-115.2109375,-12)"><foreignObject width="230.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Primary Signing CA (conditional)</div></foreignObject></g></g></g><g class="node default" id="flowchart-ExternalRootCA-7774" transform="translate(224.046875,30)" style="opacity: 1;"><rect rx="0" ry="0" x="-105.59375" y="-22" width="211.1875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-95.59375,-12)"><foreignObject width="191.1875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">External RootCA (optional)</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertAgentPrimary-7778" transform="translate(108.10546875,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-90.2109375" y="-22" width="180.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-80.2109375,-12)"><foreignObject width="160.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Client Agent</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertServicePrimary-7779" transform="translate(319.98828125,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-71.671875" y="-22" width="143.34375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-61.671875,-12)"><foreignObject width="123.34375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Service</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertAgentSecondary-7780" transform="translate(536.03515625,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-90.2109375" y="-22" width="180.421875" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-80.2109375,-12)"><foreignObject width="160.421875" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Client Agent</div></foreignObject></g></g></g><g class="node default" id="flowchart-LeafCertServiceSecondary-7781" transform="translate(747.91796875,387)" style="opacity: 1;"><rect rx="0" ry="0" x="-71.671875" y="-22" width="143.34375" height="44" class="label-container"></rect><g class="label" transform="translate(0,0)"><g transform="translate(-61.671875,-12)"><foreignObject width="123.34375" height="24"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; white-space: nowrap;">Leaf Cert Service</div></foreignObject></g></g></g></g></g></g></svg>
\ No newline at end of file