diff --git a/docs/docs/architecture/components/service-mesh.md b/docs/docs/architecture/components/service-mesh.md index a4d0661f30..58b082e1a8 100644 --- a/docs/docs/architecture/components/service-mesh.md +++ b/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. diff --git a/docs/docs/architecture/secrets.md b/docs/docs/architecture/secrets.md index 472a92b93a..c2cedcd7a9 100644 --- a/docs/docs/architecture/secrets.md +++ b/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`. diff --git a/docs/docs/howto/manifest-update.md b/docs/docs/howto/manifest-update.md index 61bb7d7bd9..161464b943 100644 --- a/docs/docs/howto/manifest-update.md +++ b/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 ``` 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. diff --git a/docs/versioned_docs/version-1.17/architecture/components/service-mesh.md b/docs/versioned_docs/version-1.17/architecture/components/service-mesh.md index 1bb7b2f590..1fccc75e33 100644 --- a/docs/versioned_docs/version-1.17/architecture/components/service-mesh.md +++ b/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. diff --git a/docs/versioned_docs/version-1.17/architecture/secrets.md b/docs/versioned_docs/version-1.17/architecture/secrets.md index 472a92b93a..c2cedcd7a9 100644 --- a/docs/versioned_docs/version-1.17/architecture/secrets.md +++ b/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`. diff --git a/docs/versioned_docs/version-1.17/howto/manifest-update.md b/docs/versioned_docs/version-1.17/howto/manifest-update.md index 61bb7d7bd9..161464b943 100644 --- a/docs/versioned_docs/version-1.17/howto/manifest-update.md +++ b/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 ``` 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.