docs: add site about certificates

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.

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',
             },
           ]
         },