From a66eb1bf397c4c8ea1e7a136758e8f45624df421 Mon Sep 17 00:00:00 2001 From: Leonard Cohnen Date: Mon, 22 Apr 2024 00:30:31 +0200 Subject: [PATCH] docs: add site about certificates --- docs/docs/_media/contrast_pki.drawio.svg | 4 ++ .../certificates-and-identities/pki.md | 0 docs/docs/architecture/certificates.md | 70 +++++++++++++++++++ docs/sidebars.js | 15 +--- 4 files changed, 77 insertions(+), 12 deletions(-) create mode 100644 docs/docs/_media/contrast_pki.drawio.svg delete mode 100644 docs/docs/architecture/certificates-and-identities/pki.md create mode 100644 docs/docs/architecture/certificates.md diff --git a/docs/docs/_media/contrast_pki.drawio.svg b/docs/docs/_media/contrast_pki.drawio.svg new file mode 100644 index 0000000000..386d2215c2 --- /dev/null +++ b/docs/docs/_media/contrast_pki.drawio.svg @@ -0,0 +1,4 @@ + + + +
Root CA








Root CA Certificate
Root CA
Private Key
Intermediate CA








Intermediate CA
Certificate
Intermediate CA
Private Key
Mesh CA
Certificate
Mesh








Mesh Certificate
Mesh Private Key
signs
signs
signs
signs
 diff --git a/docs/docs/architecture/certificates-and-identities/pki.md b/docs/docs/architecture/certificates-and-identities/pki.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/docs/architecture/certificates.md b/docs/docs/architecture/certificates.md new file mode 100644 index 0000000000..f5d1c82687 --- /dev/null +++ b/docs/docs/architecture/certificates.md @@ -0,0 +1,70 @@ +# Certificate authority + +The Coordinator acts as a certificate authority (CA) for the workloads +defined in the manifest. +After a workload pod's attestation has been verified by the Coordinator, +it receives a mesh certificate and the mesh CA certificate. +The mesh certificate can be used for example in a TLS connection as the server or +client certificate to proof to the other party that the workload has been +verified by the Coordinator. The other party can verify the mesh certificate +with the mesh CA certificate. While the certificates can be used by the workload +developer in different ways, they're automatically used in Contrast's service +mesh to establish mTLS connections between workloads in the same deployment. + +## Public key infrastructure + +The Coordinator establishes a public key infrastructure (PKI) for all workloads +contained in the manifest. The Coordinator holds three certificates: the root CA +certificate, the intermediate CA certificate, and the mesh CA certificate. +The root CA certificate is a long-lasting certificate and its private key signs +the intermediate CA certificate. The intermediate CA certificate and the mesh CA +certificate share the same private key. This intermediate private key is used +to sign the mesh certificates. Moreover, the intermediate private key and +therefore the intermediate CA certificate and the mesh CA certificate are +rotated when setting a new manifest. + +![PKI certificate chain](../_media/contrast_pki.drawio.svg) + +## Certificate rotation + +Depending on the configuration of the first manifest, it allows the workload +owner to update the manifest and, therefore, the deployment. +Workload owners and data owners can be mutually untrusted parties. +To protect against the workload owner silently introducing malicious containers, +the Coordinator rotates the intermediate private key every time the manifest is +updated and, therefore, the +intermediate CA certificate and mesh CA certificate. If the user doesn't +trust the workload owner, they use the mesh CA certificate obtained when they +verified the Coordinator and the manifest. This ensures that the user only +connects to workloads defined in the manifest they verified since only those +workloads' certificates are singed with this intermediate private key. + +Similarly, the service mesh also uses the mesh CA certificate obtained when the +workload was started, so the workload only trusts endpoints that have been +verified by the Coordinator based on the same manifest. Consequently, a +manifest update requires a fresh rollout of the services in the service mesh. + +## Usage of the different certificates + +- The **root CA certificate** is returned when verifying the Coordinator. +The data owner can use it to verify the mesh certificates of the workloads. +This should only be used if the data owner trusts all future updates to the +manifest and workloads. This is, for instance, the case when the workload owner is +the same person as the data owner. +- The **mesh CA certificate** is returned when verifying the Coordinator. +The data owner can use it to verify the mesh certificates of the workloads. +This certificate is bound to the manifest set when the Coordinator is verified. +If the manifest is updated, the mesh CA certificate changes. +New workloads will receive mesh certificates signed by the _new_ mesh CA certificate. +The Coordinator with the new manifest needs to be verified to retrieve the new mesh CA certificate. +The service mesh also uses the mesh CA certificate to verify the mesh certificates. +- The **intermediate CA certificate** links the root CA certificate to the +mesh certificate so that the mesh certificate can be verified with the root CA +certificate. It's part of the certificate chain handed out by +endpoints in the service mesh. +- The **mesh certificate** is part of the certificate chain handed out by +endpoints in the service mesh. During the startup of a pod, the Initializer +requests a certificate from the Coordinator. This mesh certificate will be returned if the Coordinator successfully +verifies the workload. The mesh certificate +contains X.509 extensions with information from the workloads attestation +document. diff --git a/docs/sidebars.js b/docs/sidebars.js index 74dc45b8c3..8bc12919ee 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -150,18 +150,9 @@ const sidebars = { ] }, { - type: 'category', - label: 'Certificates and Identities', - link: { - type: 'generated-index', - }, - items: [ - { - type: 'doc', - label: 'PKI', - id: 'architecture/certificates-and-identities/pki', - }, - ] + type: 'doc', + label: 'Certificate authority', + id: 'architecture/certificates', }, ] },