From 196f6ab28f968c8da1a14ca54e0e28cc7bd1a379 Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Wed, 24 May 2023 17:21:57 +0000 Subject: [PATCH 1/4] A65: mTLS Credentials in xDS Bootstrap File --- A65-xds-mtls-creds-in-bootstrap.md | 91 ++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 A65-xds-mtls-creds-in-bootstrap.md diff --git a/A65-xds-mtls-creds-in-bootstrap.md b/A65-xds-mtls-creds-in-bootstrap.md new file mode 100644 index 000000000..ed802fa65 --- /dev/null +++ b/A65-xds-mtls-creds-in-bootstrap.md @@ -0,0 +1,91 @@ +A65: mTLS Credentials in xDS Bootstrap File +---- +* Author(s): @markdroth +* Approver: @ejona86 +* Status: {Draft, In Review, Ready for Implementation, Implemented} +* Implemented in: +* Last updated: 2023-05-24 +* Discussion at: (filled after thread exists) + +## Abstract + +This proposal adds support for configuring the use of mTLS for +communicating with the xDS server via the xDS bootstrap file. + +## Background + +[gRFC A27][A27] defines the xDS bootstrap file format for setting +the channel creds used to communicate with the xDS server, with the +initial options of `google_default` and `insecure`. It suggested that a +general-purpose mechanism could be added to configure arbitrary channel +creds types, which has subsequently been done, albeit not intended as +a public API. + +[gRFC A29][A29] describes the certificate provider framework used for +configuring mTLS for data plane communication in xDS. It also defines +the file-watcher certificate provider. + +This proposal defines a new channel creds type to be used in the +bootstrap file for using mTLS with the xDS server, leveraging the +functionality of the file-watcher certificate provider. + +### Related Proposals: +* [gRFC A27: xDS-Based Global Load Balancing][A27] +* [gRFC A29: xDS-Based Security for gRPC Clients and Servers][A29] + +## Proposal + +We will define a new credential type in the bootstrap file called `tls`. +Its configuration will be the same as that of the file-watcher +certificate provider described in [gRFC A29][A29]. Specifically, the +config will look like this: + +```json +{ + // Path to identity certificate file. + // If set, mTLS will be used; if unset, normal TLS will be used. + "certificate_file": , + + // Paths to private key and CA certificate files. + // If either of these fields are set, both must be set. + // If neither is set, system-wide root certs are used. + "private_key_file": , + "ca_certificate_file": , + + // How often to re-read the certificate files. + // Value is the JSON format described for a google.protobuf.Duration + // message in https://protobuf.dev/programming-guides/proto3/#json. + // If unset, defaults to 10 minutes. + "refresh_interval": +} +``` + +Implementations should be able to internally configure the use of the +file-watcher certificate provider for the certificate-reloading +functionality. + +### Temporary environment variable protection + +This feature is not enabled via I/O, so no env var protection is needed. + +## Rationale + +We considered phrasing the credential config in a way that exposes the +certificate provider framework directly, since that would have allowed it +to automatically support any new cert provider implementations we may +add in the future. However, the plumbing for that turned out to be a +bit challenging, so we decided to only directly expose the file-watcher +certificate provider mechanism. If we add other certificate providers +in the future, we can consider adding fields to expose them in this +configuration. + +## Implementation + +Implemented in C-core in https://github.com/grpc/grpc/pull/33234. + +## Open issues (if applicable) + +N/A + +[A27]: A27-xds-global-load-balancing.md +[A29]: A29-xds-tls-security.md From dad7d5e049a116d36805749778a81c3bf52daa90 Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Wed, 24 May 2023 17:25:20 +0000 Subject: [PATCH 2/4] add mailing list link --- A65-xds-mtls-creds-in-bootstrap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A65-xds-mtls-creds-in-bootstrap.md b/A65-xds-mtls-creds-in-bootstrap.md index ed802fa65..3e41bd423 100644 --- a/A65-xds-mtls-creds-in-bootstrap.md +++ b/A65-xds-mtls-creds-in-bootstrap.md @@ -5,7 +5,7 @@ A65: mTLS Credentials in xDS Bootstrap File * Status: {Draft, In Review, Ready for Implementation, Implemented} * Implemented in: * Last updated: 2023-05-24 -* Discussion at: (filled after thread exists) +* Discussion at: https://groups.google.com/g/grpc-io/c/h_LQnTimyt4 ## Abstract From 0056fd1213d6634d2931764938a831e98b210edc Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Thu, 25 May 2023 20:07:12 +0000 Subject: [PATCH 3/4] note config behavior difference --- A65-xds-mtls-creds-in-bootstrap.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/A65-xds-mtls-creds-in-bootstrap.md b/A65-xds-mtls-creds-in-bootstrap.md index 3e41bd423..a7319d7e6 100644 --- a/A65-xds-mtls-creds-in-bootstrap.md +++ b/A65-xds-mtls-creds-in-bootstrap.md @@ -36,7 +36,7 @@ functionality of the file-watcher certificate provider. ## Proposal We will define a new credential type in the bootstrap file called `tls`. -Its configuration will be the same as that of the file-watcher +Its configuration will be essentially the same as that of the file-watcher certificate provider described in [gRFC A29][A29]. Specifically, the config will look like this: @@ -60,6 +60,12 @@ config will look like this: } ``` +The only difference between the file-watcher certificate provider config +and this one is that in the file-watcher certificate provider, at least +one of the "certificate_file" or "ca_certificate_file" fields must be +specified, whereas in this configuration, it is acceptable to specify +neither one. + Implementations should be able to internally configure the use of the file-watcher certificate provider for the certificate-reloading functionality. From ba29b258aeb7584179ce0a3d70db328377657d33 Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Fri, 26 May 2023 18:49:09 +0000 Subject: [PATCH 4/4] review comments --- A65-xds-mtls-creds-in-bootstrap.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/A65-xds-mtls-creds-in-bootstrap.md b/A65-xds-mtls-creds-in-bootstrap.md index a7319d7e6..9356b7315 100644 --- a/A65-xds-mtls-creds-in-bootstrap.md +++ b/A65-xds-mtls-creds-in-bootstrap.md @@ -42,20 +42,20 @@ config will look like this: ```json { - // Path to identity certificate file. - // If set, mTLS will be used; if unset, normal TLS will be used. - "certificate_file": , + // Path to CA certificate file. + // If unset, system-wide root certs are used. + "ca_certificate_file": , - // Paths to private key and CA certificate files. + // Paths to identity certificate file and private key file. // If either of these fields are set, both must be set. - // If neither is set, system-wide root certs are used. + // If set, mTLS will be used; if unset, normal TLS will be used. + "certificate_file": , "private_key_file": , - "ca_certificate_file": , // How often to re-read the certificate files. // Value is the JSON format described for a google.protobuf.Duration // message in https://protobuf.dev/programming-guides/proto3/#json. - // If unset, defaults to 10 minutes. + // If unset, defaults to "600s". "refresh_interval": } ``` @@ -72,7 +72,10 @@ functionality. ### Temporary environment variable protection -This feature is not enabled via I/O, so no env var protection is needed. +This feature is not enabled via remote I/O, and we don't have a good way +to interop test it, so we will not use env var protection for this feature. +Unit tests in individual languages should be sufficient to verify the +functionality. ## Rationale