docs: explain cert lifetime and rotation

docs/docs/architecture/components/service-mesh.md

@@ -223,6 +223,18 @@ This mechanism protects against scenarios where a workload owner introduces unau
 
 Similarly, the service mesh uses the mesh CA certificate issued when the workload was verified. Any change to the manifest requires a new rollout of the services, as the mesh CA certificate will change.
 
+:::info
+
+The Coordinator root, intermediate and mesh CA certificates are valid for 10 years from the instant of the `contrast set` operation, while the workload certificates are valid for one year.
+These lifetimes are chosen to be larger than the expected lifetime of a pod using the certificates.
+However, the practical validity of the certificates is determined by the Coordinator manifest lifecycle and the uptime of individual pods.
+The service mesh container will only accept certificates issued by the mesh CA that issued its own certificate.
+
+If shorter certificate or key lifetimes are desired for some other reason, the certificates can be rotated with a [manifest update](../../howto/manifest-update.md).
+Note that the root CA certificate can't be rotated without deploying a new Coordinator.
+
+:::
+
 ### Service mesh integration
 
 The service mesh relies on the mesh certificates to establish mutual TLS (mTLS) connections between workloads.

docs/docs/architecture/secrets.md

@@ -92,8 +92,9 @@ spec:
 ### Transit secrets engine
 
 In addition to the workload secrets provisioned by the initializer, Contrast workloads can ask the Coordinator to encrypt and decrypt secrets on their behalf.
-The corresponding HTTP API is compatible with a subset of the [transit secrets API](https://openbao.org/api-docs/secret/transit/) used by [HashiCorp Vault](https://www.hashicorp.com/en/products/vault), and is served on Coordinator port 8200.
+The corresponding API is compatible with a subset of the [transit secrets API](https://openbao.org/api-docs/secret/transit/) used by [HashiCorp Vault](https://www.hashicorp.com/en/products/vault), and is served on Coordinator port 8200.
 Its primary use case is [auto-unsealing of Vault deployments](../howto/vault.md), which can in turn provide fine-grained secrets management to Contrast workloads.
+Workloads can access the transit secrets API over HTTPS, authenticating with the [mesh certificate](components/service-mesh.md#public-key-infrastructure).
 
 Workloads can only access the encryption key with the same name as their `WorkloadSecretID`.
 For example, if the workload secret ID in the manifest is `my-secret-id`, they can use the endpoints `/v1/transit/encrypt/my-secret-id` and `/v1/transit/decrypt/my-secret-id`.

docs/docs/howto/manifest-update.md

@@ -13,7 +13,6 @@ If the manifest changes, for example, due to modifications in the service mesh c
 
 ## How-to
 
-
 Set the changed manifest at the Coordinator with:
 
 ```sh
@@ -39,3 +38,9 @@ kubectl rollout restart <resource>
 ```
 
 for all your application resources.
+
+### Updates for certificate rotation
+
+As described above, a manifest update triggers rotation of the mesh CA certificate, the intermediate CA certificate and the workload certificates.
+You can use this to force a certificate rotation or to constrain the certificate validity period.
+Setting the current manifest once more causes a certificate rotation, without changing the reference values enforced by the Coordinator.

docs/versioned_docs/version-1.17/architecture/components/service-mesh.md

@@ -223,6 +223,18 @@ This mechanism protects against scenarios where a workload owner introduces unau
 
 Similarly, the service mesh uses the mesh CA certificate issued when the workload was verified. Any change to the manifest requires a new rollout of the services, as the mesh CA certificate will change.
 
+:::info
+
+The Coordinator root, intermediate and mesh CA certificates are valid for 10 years from the instant of the `contrast set` operation, while the workload certificates are valid for one year.
+These lifetimes are chosen to be larger than the expected lifetime of a pod using the certificates.
+However, the practical validity of the certificates is determined by the Coordinator manifest lifecycle and the uptime of individual pods.
+The service mesh container will only accept certificates issued by the mesh CA that issued its own certificate.
+
+If shorter certificate or key lifetimes are desired for some other reason, the certificates can be rotated with a [manifest update](../../howto/manifest-update.md).
+Note that the root CA certificate can't be rotated without deploying a new Coordinator.
+
+:::
+
 ### Service mesh integration
 
 The service mesh relies on the mesh certificates to establish mutual TLS (mTLS) connections between workloads.

docs/versioned_docs/version-1.17/architecture/secrets.md

@@ -92,8 +92,9 @@ spec:
 ### Transit secrets engine
 
 In addition to the workload secrets provisioned by the initializer, Contrast workloads can ask the Coordinator to encrypt and decrypt secrets on their behalf.
-The corresponding HTTP API is compatible with a subset of the [transit secrets API](https://openbao.org/api-docs/secret/transit/) used by [HashiCorp Vault](https://www.hashicorp.com/en/products/vault), and is served on Coordinator port 8200.
+The corresponding API is compatible with a subset of the [transit secrets API](https://openbao.org/api-docs/secret/transit/) used by [HashiCorp Vault](https://www.hashicorp.com/en/products/vault), and is served on Coordinator port 8200.
 Its primary use case is [auto-unsealing of Vault deployments](../howto/vault.md), which can in turn provide fine-grained secrets management to Contrast workloads.
+Workloads can access the transit secrets API over HTTPS, authenticating with the [mesh certificate](components/service-mesh.md#public-key-infrastructure).
 
 Workloads can only access the encryption key with the same name as their `WorkloadSecretID`.
 For example, if the workload secret ID in the manifest is `my-secret-id`, they can use the endpoints `/v1/transit/encrypt/my-secret-id` and `/v1/transit/decrypt/my-secret-id`.

docs/versioned_docs/version-1.17/howto/manifest-update.md

@@ -13,7 +13,6 @@ If the manifest changes, for example, due to modifications in the service mesh c
 
 ## How-to
 
-
 Set the changed manifest at the Coordinator with:
 
 ```sh
@@ -39,3 +38,9 @@ kubectl rollout restart <resource>
 ```
 
 for all your application resources.
+
+### Updates for certificate rotation
+
+As described above, a manifest update triggers rotation of the mesh CA certificate, the intermediate CA certificate and the workload certificates.
+You can use this to force a certificate rotation or to constrain the certificate validity period.
+Setting the current manifest once more causes a certificate rotation, without changing the reference values enforced by the Coordinator.