diff --git a/api/envoy/extensions/transport_sockets/tls/v3/common.proto b/api/envoy/extensions/transport_sockets/tls/v3/common.proto index 587e3271836b..2b545b35ee12 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/api/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -155,7 +155,8 @@ message TlsCertificate { // default the parent directories of the filesystem paths in // *certificate_chain* and *private_key* are watched if this field is not // specified. This only applies when a *TlsCertificate* is delivered by SDS - // with references to filesystem paths. + // with references to filesystem paths. See the :ref:`SDS key rotation + // ` documentation for further details. config.core.v3.WatchedDirectory watched_directory = 7; // BoringSSL private key method provider. This is an alternative to :ref:`private_key @@ -265,7 +266,8 @@ message CertificateValidationContext { // default the parent directory of the filesystem path in *trusted_ca* is // watched if this field is not specified. This only applies when a // *CertificateValidationContext* is delivered by SDS with references to - // filesystem paths. + // filesystem paths. See the :ref:`SDS key rotation ` + // documentation for further details. config.core.v3.WatchedDirectory watched_directory = 11; // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the diff --git a/api/envoy/extensions/transport_sockets/tls/v4alpha/common.proto b/api/envoy/extensions/transport_sockets/tls/v4alpha/common.proto index b2fa6f672628..30859bc2a3eb 100644 --- a/api/envoy/extensions/transport_sockets/tls/v4alpha/common.proto +++ b/api/envoy/extensions/transport_sockets/tls/v4alpha/common.proto @@ -157,7 +157,8 @@ message TlsCertificate { // default the parent directories of the filesystem paths in // *certificate_chain* and *private_key* are watched if this field is not // specified. This only applies when a *TlsCertificate* is delivered by SDS - // with references to filesystem paths. + // with references to filesystem paths. See the :ref:`SDS key rotation + // ` documentation for further details. config.core.v4alpha.WatchedDirectory watched_directory = 7; // BoringSSL private key method provider. This is an alternative to :ref:`private_key @@ -267,7 +268,8 @@ message CertificateValidationContext { // default the parent directory of the filesystem path in *trusted_ca* is // watched if this field is not specified. This only applies when a // *CertificateValidationContext* is delivered by SDS with references to - // filesystem paths. + // filesystem paths. See the :ref:`SDS key rotation ` + // documentation for further details. config.core.v4alpha.WatchedDirectory watched_directory = 11; // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the diff --git a/docs/root/configuration/security/secret.rst b/docs/root/configuration/security/secret.rst index fdbc88242d02..5ad3650cc19e 100644 --- a/docs/root/configuration/security/secret.rst +++ b/docs/root/configuration/security/secret.rst @@ -45,11 +45,15 @@ refer to filesystem paths. This currently is supported for the following secret * :ref:`TlsCertificate ` * :ref:`CertificateValidationContext ` -By default, directories containing secrets are watched for filesystem move events. Explicit control over -the watched directory is possible by specifying a *watched_directory* path in :ref:`TlsCertificate +By default, directories containing secrets are watched for filesystem move events. For example, a +key or trusted CA certificates at ``/foo/bar/baz/cert.pem`` will be watched at `/foo/bar/baz`. +Explicit control over the watched directory is possible by specifying a *watched_directory* path in +:ref:`TlsCertificate ` and :ref:`CertificateValidationContext `. +This allows watches to be established at path predecessors, e.g. ``/foo/bar``; this capability is +useful when implementing common key rotation schemes. An example of key rotation is provided :ref:`below `. diff --git a/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/common.proto b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/common.proto index c5452fced643..2ddca5720fc8 100644 --- a/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -154,7 +154,8 @@ message TlsCertificate { // default the parent directories of the filesystem paths in // *certificate_chain* and *private_key* are watched if this field is not // specified. This only applies when a *TlsCertificate* is delivered by SDS - // with references to filesystem paths. + // with references to filesystem paths. See the :ref:`SDS key rotation + // ` documentation for further details. config.core.v3.WatchedDirectory watched_directory = 7; // BoringSSL private key method provider. This is an alternative to :ref:`private_key @@ -262,7 +263,8 @@ message CertificateValidationContext { // default the parent directory of the filesystem path in *trusted_ca* is // watched if this field is not specified. This only applies when a // *CertificateValidationContext* is delivered by SDS with references to - // filesystem paths. + // filesystem paths. See the :ref:`SDS key rotation ` + // documentation for further details. config.core.v3.WatchedDirectory watched_directory = 11; // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the diff --git a/generated_api_shadow/envoy/extensions/transport_sockets/tls/v4alpha/common.proto b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v4alpha/common.proto index b2fa6f672628..30859bc2a3eb 100644 --- a/generated_api_shadow/envoy/extensions/transport_sockets/tls/v4alpha/common.proto +++ b/generated_api_shadow/envoy/extensions/transport_sockets/tls/v4alpha/common.proto @@ -157,7 +157,8 @@ message TlsCertificate { // default the parent directories of the filesystem paths in // *certificate_chain* and *private_key* are watched if this field is not // specified. This only applies when a *TlsCertificate* is delivered by SDS - // with references to filesystem paths. + // with references to filesystem paths. See the :ref:`SDS key rotation + // ` documentation for further details. config.core.v4alpha.WatchedDirectory watched_directory = 7; // BoringSSL private key method provider. This is an alternative to :ref:`private_key @@ -267,7 +268,8 @@ message CertificateValidationContext { // default the parent directory of the filesystem path in *trusted_ca* is // watched if this field is not specified. This only applies when a // *CertificateValidationContext* is delivered by SDS with references to - // filesystem paths. + // filesystem paths. See the :ref:`SDS key rotation ` + // documentation for further details. config.core.v4alpha.WatchedDirectory watched_directory = 11; // An optional list of base64-encoded SHA-256 hashes. If specified, Envoy will verify that the