docs: highlight importance of seedshare owner key

Co-authored-by: Thomas Tendyck <[email protected]>

docs/docs/architecture/secrets.md

@@ -7,6 +7,16 @@ This derivation is deterministic, so the seed can be used to bring any Coordinat
 The secret seed is returned to the user on the first call to `contrast set`, encrypted with the user's public seed share owner key.
 If no seed share owner key is provided, a key is generated and stored in the working directory.
 
+:::danger
+
+The secret seed and the seed share owner key are highly sensitive.
+
+* If either of them leak, the Contrast deployment should be considered compromised.
+* If the secret seed is lost, data encrypted with Contrast secrets can't be recovered.
+* If the seed share owner key is lost, the Coordinator can't be recovered and needs to be redeployed with a new manifest.
+
+:::
+
 ## Persistence
 
 The Coordinator runs as a `StatefulSet` with a dynamically provisioned persistent volume.
@@ -19,9 +29,9 @@ Thus, the manifest is stored in plain text, but is signed with a private key der
 
 When a Coordinator starts up, it doesn't have access to the signing secret and can thus not verify the integrity of the persisted manifests.
 It needs to be provided with the secret seed, from which it can derive the signing key that verifies the signatures.
-This procedure is called recovery and is initiated by the workload owner.
+This procedure is called recovery and is initiated by the seed share owner.
 The CLI decrypts the secret seed using the private seed share owner key, verifies the Coordinator and sends the seed through the `Recover` method.
-The Coordinator recovers its key material and verifies the manifest history signature.
+The Coordinator authenticates the seed share owner, recovers its key material, and verifies the manifest history signature.
 
 ## Workload Secrets
 
@@ -31,9 +41,8 @@ Like the workload certificates, it's written to the `secrets/workload-secret-see
 
 :::warning
 
-The workload owner can decrypt data encrypted with secrets derived from the workload secret.
-The workload owner can derive the workload secret themselves, since it's derived from the secret seed known to the workload owner.
-If the data owner and the workload owner is the same entity, then they can safely use the workload secrets.
+The seed share owner can decrypt data encrypted with secrets derived from the workload secret, because they can themselves derive the workload secret.
+If the data owner fully trusts the seed share owner (when they are the same entity, for example), they can securely use the workload secrets.
 
 :::
 

docs/docs/deployment.md

@@ -303,6 +303,13 @@ If you don't know the correct values use `ffffffffffffffffffffffffffffffff` and
 Please be aware that runtime policies currently have some blind spots. For example, they can't guarantee the starting order of containers. See the [current limitations](features-limitations.md#runtime-policies) for more details.
 :::
 
+Running `contrast generate` for the first time creates some additional files in the working directory:
+
+* `seedshare-owner.pem` is required for handling the secret seed and recovering the Coordinator (see [Secrets & recovery](architecture/secrets.md)).
+* `workload-owner.pem` is required for manifest updates after the initial `contrast set`.
+* `rules.rego` and `settings.json` are the basis for [runtime policies](components/policies.md).
+* `layers-cache.json` caches container image layer information for your deployments to speed up subsequent runs of `contrast generate`.
+
 If you don't want the Contrast Initializer to automatically be added to your
 workloads, there are two ways you can skip the Initializer injection step,
 depending on how you want to customize your deployment.
@@ -480,7 +487,7 @@ kubectl delete pod -l app.kubernetes.io/name=coordinator
 
 Kubernetes schedules a new pod, but that pod doesn't have access to the key material the previous pod held in memory and can't issue certificates for workloads yet.
 You can confirm this by running `verify` again, or you can restart a workload pod, which should stay in the initialization phase.
-However, the secret seed in your working directory is sufficient to recover the coordinator.
+However, you can recover the Coordinator using the secret seed and the seed share owner key in your working directory.
 
 ```sh
 contrast recover -c "${coordinator}:1313"