From 3c1fbafadb084ef543acb7ec18bb817fe888580f Mon Sep 17 00:00:00 2001 From: Leonard Cohnen Date: Sat, 13 Apr 2024 19:59:43 +0200 Subject: [PATCH] docs: add site about certificates --- docs/docs/_media/contrast_pki.drawio.svg | 4 ++ .../certificates.md | 47 +++++++++++++++++++ .../certificates-and-identities/pki.md | 0 docs/sidebars.js | 4 +- 4 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 docs/docs/_media/contrast_pki.drawio.svg create mode 100644 docs/docs/architecture/certificates-and-identities/certificates.md delete mode 100644 docs/docs/architecture/certificates-and-identities/pki.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..a8ade2ad29 --- /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
 \ No newline at end of file diff --git a/docs/docs/architecture/certificates-and-identities/certificates.md b/docs/docs/architecture/certificates-and-identities/certificates.md new file mode 100644 index 0000000000..01bf56f5f6 --- /dev/null +++ b/docs/docs/architecture/certificates-and-identities/certificates.md @@ -0,0 +1,47 @@ +# Certificates + +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 e.g., 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 are 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 Certificate and the Mesh CA Certificate. +The Root CA Certificate is a long-lasting Certificate and it's private key singes +the Intermediate Certificate. The Intermediate 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 Certificate and the Mesh CA Certificate are +rotated when setting a new Manifest. + +![PKI Certificate chain](../../_media/contrast_pki.drawio.svg) + +The intended uses of the certificates are: + +- The **Root CA Certificate** is returned when verifying the Coordinator. It can +be used by the data owner 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 of the workload owner is +the same person as the data owner. +- The **Mesh CA Certificate** is returned when verifying the Coordinator. It can +be used by the data owner to verify the Mesh Certificates of the workloads. +This certificate is bound to Manifest set when the Coordinator was verified. +If the Manifest is updated, new workloads will receive Mesh Certificates that +are _not_ signed by the already retrieved Mesh CA Certificate certificate. +Instead, the Coordinator with the new Manifest needs to be verified to retrieve +the new Mesh CA Certificate. This Certificate is also used by the service mesh +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 is 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. While the Coordinator verifies an upcoming +workload, it creates a new Mesh Certificate and sends it to the workload. 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/sidebars.js b/docs/sidebars.js index 1797da527d..735aec14b7 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -169,8 +169,8 @@ const sidebars = { items: [ { type: 'doc', - label: 'PKI', - id: 'architecture/certificates-and-identities/pki', + label: 'Certificates', + id: 'architecture/certificates-and-identities/certificates', }, ] },