From cb564afe7998d63bc9c2408a306bf10ba7bb7636 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 11:48:21 +0530 Subject: [PATCH 01/58] Create A95-SNI-setting-and-SNI-SAN-validation --- A95-SNI-setting-and-SNI-SAN-validation | 33 ++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 A95-SNI-setting-and-SNI-SAN-validation diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation new file mode 100644 index 000000000..7dd7cc231 --- /dev/null +++ b/A95-SNI-setting-and-SNI-SAN-validation @@ -0,0 +1,33 @@ +### Background +For an overview of securing connections in the envoy proxy using SNI +and SAN validation, read [envoy-SNI]. gRPC will implement the same +behavior. + +[envoy-SNI]: https://www.envoyproxy.io/docs/envoy/latest/_sources/start/quick-start/securing.rst.txt + +### Summary of changes +* Setting SNI +xDS-managed gRPC clients will set SNI for the Tls handshake for +Tls connections using the fields from [UpstreamTlsContext][UTC] +set in the CDS resource. + +1. If [UpstreamTlsContext][UTC] specifies the SNI to use, then +it will be used. + +2. If [UpstreamTlsContext][UTC] specifies `auto_host_sni`, then +SNI will be set to the hostname, which is either the logical +DNS name for DNS clusters or the endponit hostname for EDS +clusters, as in the case of the hostname useed for authority +rewriting [Ar 81-hostname][A81-hostname]. + +[UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 +[A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md?plain=1#L85 + +* Server SAN validation against SNI used + +If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC] +gRPC client will replace any Subject Alternative Name (SAN) +validations with a validation for a DNS SAN matching the SNI value +sent. + + From b2c115af1d039a5e5a1461947a874596c2451fdd Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 12:35:35 +0530 Subject: [PATCH 02/58] Update A95-SNI-setting-and-SNI-SAN-validation --- A95-SNI-setting-and-SNI-SAN-validation | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation index 7dd7cc231..c34b27dd5 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation +++ b/A95-SNI-setting-and-SNI-SAN-validation @@ -1,15 +1,26 @@ ### Background + +In [A29][A29] for TLS security in xDS-managed connections, it +proposed that the `SNI` field from [UpstreamTlsContext.SNI][UTC_SNI] +would be ignored and [DownstreamTlsContext.require_sni][DTC_require-SNI] would +cause the LDS update to fail. In proposal changes these, and also starts +using certain other related fields for securing TLS +connections via xDS. + For an overview of securing connections in the envoy proxy using SNI -and SAN validation, read [envoy-SNI]. gRPC will implement the same -behavior. +and SAN validation, read [envoy-SNI]. +[UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 +[DTC_require-SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L115 +[A29]: A29-xds-tls-security.md [envoy-SNI]: https://www.envoyproxy.io/docs/envoy/latest/_sources/start/quick-start/securing.rst.txt -### Summary of changes +## Proposal +This proposal has two parts: * Setting SNI xDS-managed gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] -set in the CDS resource. +in a CDS update. 1. If [UpstreamTlsContext][UTC] specifies the SNI to use, then it will be used. @@ -30,4 +41,11 @@ gRPC client will replace any Subject Alternative Name (SAN) validations with a validation for a DNS SAN matching the SNI value sent. +### Related Proposals: +* [gRFC A29: xDS-Based Security for gRPC Clients and Servers][A29] +* [gRFC A81: xDS Authority Rewriting][A81] + +[A29]: A29-xds-tls-security.md +[A81]: A81-xds-authority-rewriting.md +### xds_cluster_impl LB Policy Changes From 100f370e391a863ec3c9287ea632e5f2ad214a8d Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 13:15:37 +0530 Subject: [PATCH 03/58] Update A95-SNI-setting-and-SNI-SAN-validation --- A95-SNI-setting-and-SNI-SAN-validation | 31 +++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation index c34b27dd5..0da9a3135 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation +++ b/A95-SNI-setting-and-SNI-SAN-validation @@ -2,13 +2,13 @@ In [A29][A29] for TLS security in xDS-managed connections, it proposed that the `SNI` field from [UpstreamTlsContext.SNI][UTC_SNI] -would be ignored and [DownstreamTlsContext.require_sni][DTC_require-SNI] would -cause the LDS update to fail. In proposal changes these, and also starts -using certain other related fields for securing TLS -connections via xDS. +would be ignored and [DownstreamTlsContext.require_sni][DTC_require-SNI] +would cause the LDS update to fail. In proposal changes these, +and also starts using certain other related fields for securing +TLS connections via xDS. For an overview of securing connections in the envoy proxy using SNI -and SAN validation, read [envoy-SNI]. +and SAN validation, see [envoy-SNI]. [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 [DTC_require-SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L115 @@ -49,3 +49,24 @@ sent. [A81]: A81-xds-authority-rewriting.md ### xds_cluster_impl LB Policy Changes +#### Setting SNI +As mentioned in [A29 implementation details][A29_impl-details] the +`UpstreamTlsContext` is either passed down to child policies via +channel arguments or is put in sub-channel attribute wrapped in a +`SslContextProvider`, depending on the language. This mechanism +will be augmented in the ClusterImpl LB policy to also add the +information about SNI if any that needs to be used during the +Tls handshake. To make this decision, the the LB policy will +make use of [UpstreamTlsContext.SNI][UTC_SNI] and the hostname +from `CdsUpdate` that is passed down by the Cds LB policy to the +ClusterImpl LB policy. In a language implementation dependent +way, this SNI value to set will be passed on to the Tls handling +code. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` +that is made available the `SslContext` dynamically constructed +based on the cert store to use as indicated by `UpstreamTlsContext`. +This `ProtocolNegotiators.ClientTlsHandler` will also be handed +over the SNI value by the `SslContextProvider` to use when +creating the `SslEngine` for the transport. + +[A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details +[UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 From e90f179275843968f2940650734b2a7ab164e1bf Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 14:15:25 +0530 Subject: [PATCH 04/58] Update A95-SNI-setting-and-SNI-SAN-validation --- A95-SNI-setting-and-SNI-SAN-validation | 44 ++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation index 0da9a3135..fefaba323 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation +++ b/A95-SNI-setting-and-SNI-SAN-validation @@ -1,19 +1,34 @@ +A95: xDS-Based setting SNI and server certificate SAN validation +---- +* Author: [Kannan Jayaprakasam](https://github.com/kannanjgithub) +* Approver: [Eric Anderson](https://github.com/ejona86) +* Status: Draft +* Implemented in: +* Last updated: 2025-07-25 + +## Abstract + +This proposal describes setting S + ### Background +During Tls handshake, the server presents its certificate to the client for authentication. In [A29][A29] for TLS security in xDS-managed connections, it proposed that the `SNI` field from [UpstreamTlsContext.SNI][UTC_SNI] -would be ignored and [DownstreamTlsContext.require_sni][DTC_require-SNI] -would cause the LDS update to fail. In proposal changes these, -and also starts using certain other related fields for securing -TLS connections via xDS. +would be ignored. In proposal seeks to start using this and other fields +for setting the SNI by the gRPC client. + +When using `XdsCredentials` for the transport, hostname validation +is turned off and instead SAN matching is performed against [UpstreamTlsContext.match_subject_alt_names][match_subject_alt_names]. +This proposal adds checking of SAN against the SNI provided by the client as well. For an overview of securing connections in the envoy proxy using SNI and SAN validation, see [envoy-SNI]. [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 -[DTC_require-SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L115 [A29]: A29-xds-tls-security.md [envoy-SNI]: https://www.envoyproxy.io/docs/envoy/latest/_sources/start/quick-start/securing.rst.txt +[match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 ## Proposal This proposal has two parts: @@ -64,9 +79,24 @@ way, this SNI value to set will be passed on to the Tls handling code. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed based on the cert store to use as indicated by `UpstreamTlsContext`. -This `ProtocolNegotiators.ClientTlsHandler` will also be handed -over the SNI value by the `SslContextProvider` to use when +The SNI value to use in the `SslContextProvider` will be made +available to the `ProtocolNegotiators.ClientTlsHandler` to use when creating the `SslEngine` for the transport. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 + +#### SAN SNI validation +The server certificate validation described in [A29 SAN matching][A29_SAN-matching] +matches the Subject Alternative Names specified in the server certificate against +[`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. +When `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], it will +take precedence, and matching will be performed against the SNI that was used by the +client, and will be made available to the code performing SAN validation in a +language dependent way, for example in Java, it is the `X509TrustManager` that +performs the SAN validation and is created by the protocol negotiating code, that +will be made available the SNI value to check against, by the `SslContextProvider`. + +[A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks +[match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 +[UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 From 5a75055dd4e8224a577f7a5fa43e6b6b32203fbf Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 15:03:36 +0530 Subject: [PATCH 05/58] Update A95-SNI-setting-and-SNI-SAN-validation --- A95-SNI-setting-and-SNI-SAN-validation | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation index fefaba323..a9190e9a3 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation +++ b/A95-SNI-setting-and-SNI-SAN-validation @@ -12,13 +12,19 @@ This proposal describes setting S ### Background -During Tls handshake, the server presents its certificate to the client for authentication. +During Tls handshake, the server presents its certificate to the client for authentication. For servers +serving multiple domains, the client needs to indicate which domain it is requesting, so that the server +can present the certificate is has for that domain. The client does this at the time of Tls handshaking +via Server Name Indication (SNI). When using `XdsChannelCredentials` for a channel, the gRPC client needs +to be configured by the xDS server with what value to send for SNI and the gRPC client should use it for +the Tls handshake. + In [A29][A29] for TLS security in xDS-managed connections, it proposed that the `SNI` field from [UpstreamTlsContext.SNI][UTC_SNI] would be ignored. In proposal seeks to start using this and other fields for setting the SNI by the gRPC client. -When using `XdsCredentials` for the transport, hostname validation +When using `XdsChannelCredentials` for the transport, hostname validation is turned off and instead SAN matching is performed against [UpstreamTlsContext.match_subject_alt_names][match_subject_alt_names]. This proposal adds checking of SAN against the SNI provided by the client as well. From 7568a91df2d70021b76f88751e023d197eda1e72 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 15:08:20 +0530 Subject: [PATCH 06/58] Rename A95-SNI-setting-and-SNI-SAN-validation to A95-SNI-setting-and-SNI-SAN-validation.md --- ...NI-SAN-validation => A95-SNI-setting-and-SNI-SAN-validation.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename A95-SNI-setting-and-SNI-SAN-validation => A95-SNI-setting-and-SNI-SAN-validation.md (100%) diff --git a/A95-SNI-setting-and-SNI-SAN-validation b/A95-SNI-setting-and-SNI-SAN-validation.md similarity index 100% rename from A95-SNI-setting-and-SNI-SAN-validation rename to A95-SNI-setting-and-SNI-SAN-validation.md From 78a3609b6c27971c9dbbb9823ee4c58ed12c2fc4 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 15:11:19 +0530 Subject: [PATCH 07/58] Update A95-SNI-setting-and-SNI-SAN-validation.md --- A95-SNI-setting-and-SNI-SAN-validation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A95-SNI-setting-and-SNI-SAN-validation.md index a9190e9a3..c10ae940b 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation.md +++ b/A95-SNI-setting-and-SNI-SAN-validation.md @@ -8,7 +8,8 @@ A95: xDS-Based setting SNI and server certificate SAN validation ## Abstract -This proposal describes setting S +gRPC will add support for setting Server Name Indication (SNI) and validation of server certificate's +Subject Alternative Names (SANs) aginst the SNI that was used. ### Background From 377632798e2d38dbf0f7f2e01cdf18cfabe1aa6c Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 17:25:56 +0530 Subject: [PATCH 08/58] Update A95-SNI-setting-and-SNI-SAN-validation.md --- A95-SNI-setting-and-SNI-SAN-validation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A95-SNI-setting-and-SNI-SAN-validation.md index c10ae940b..357b9544a 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation.md +++ b/A95-SNI-setting-and-SNI-SAN-validation.md @@ -97,12 +97,12 @@ creating the `SslEngine` for the transport. The server certificate validation described in [A29 SAN matching][A29_SAN-matching] matches the Subject Alternative Names specified in the server certificate against [`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. -When `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], it will -take precedence, and matching will be performed against the SNI that was used by the +When `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], independent of +the above validation, matching will be performed against the SNI that was used by the client, and will be made available to the code performing SAN validation in a -language dependent way, for example in Java, it is the `X509TrustManager` that -performs the SAN validation and is created by the protocol negotiating code, that -will be made available the SNI value to check against, by the `SslContextProvider`. +language dependent way, for example in Java, the SNI used will be set in the +`XdsX509TrustManager` that performs the SAN validation and is set in the `SslContext` +used for the handshake. [A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 From 78eb65a69ed27a82ec667e6dc49054889c61e94d Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 17:30:22 +0530 Subject: [PATCH 09/58] Update A95-SNI-setting-and-SNI-SAN-validation.md --- A95-SNI-setting-and-SNI-SAN-validation.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A95-SNI-setting-and-SNI-SAN-validation.md index 357b9544a..c717ed40f 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation.md +++ b/A95-SNI-setting-and-SNI-SAN-validation.md @@ -107,3 +107,7 @@ used for the handshake. [A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 + +### Temporary environment variable protection +Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` +env var. The env var guard will be removed once the feature passes interop tests. From cf3d0d2184869ee96769dfb816d237a0677e378a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 17:50:31 +0530 Subject: [PATCH 10/58] Update A95-SNI-setting-and-SNI-SAN-validation.md --- A95-SNI-setting-and-SNI-SAN-validation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A95-SNI-setting-and-SNI-SAN-validation.md index c717ed40f..aba7ff7fd 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation.md +++ b/A95-SNI-setting-and-SNI-SAN-validation.md @@ -42,7 +42,7 @@ This proposal has two parts: * Setting SNI xDS-managed gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] -in a CDS update. +in the CDS update. 1. If [UpstreamTlsContext][UTC] specifies the SNI to use, then it will be used. @@ -59,8 +59,7 @@ rewriting [Ar 81-hostname][A81-hostname]. * Server SAN validation against SNI used If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC] -gRPC client will replace any Subject Alternative Name (SAN) -validations with a validation for a DNS SAN matching the SNI value +gRPC client will perform validation for a DNS SAN matching the SNI value sent. ### Related Proposals: @@ -97,9 +96,10 @@ creating the `SslEngine` for the transport. The server certificate validation described in [A29 SAN matching][A29_SAN-matching] matches the Subject Alternative Names specified in the server certificate against [`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. -When `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], independent of -the above validation, matching will be performed against the SNI that was used by the -client, and will be made available to the code performing SAN validation in a +If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], matching will be +performed against the SNI that was used by the client, and this validation will replace +the [`match_subject_alt_names`][match_subject_alt_names] if set. The SNI to check +aggainst will be made available to the code performing SAN validation in a language dependent way, for example in Java, the SNI used will be set in the `XdsX509TrustManager` that performs the SAN validation and is set in the `SslContext` used for the handshake. @@ -108,6 +108,6 @@ used for the handshake. [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 -### Temporary environment variable protection +#### Temporary environment variable protection Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` env var. The env var guard will be removed once the feature passes interop tests. From 80b9db44d4fafa8c3e5a3e8d41cadd972e68fa7b Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 17:52:13 +0530 Subject: [PATCH 11/58] Update A95-SNI-setting-and-SNI-SAN-validation.md --- A95-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A95-SNI-setting-and-SNI-SAN-validation.md index aba7ff7fd..df0896fe9 100644 --- a/A95-SNI-setting-and-SNI-SAN-validation.md +++ b/A95-SNI-setting-and-SNI-SAN-validation.md @@ -1,4 +1,4 @@ -A95: xDS-Based setting SNI and server certificate SAN validation +A98: xDS-Based setting SNI and server certificate SAN validation ---- * Author: [Kannan Jayaprakasam](https://github.com/kannanjgithub) * Approver: [Eric Anderson](https://github.com/ejona86) From f12d716934d6210ce5515f0781ad73a2931ad76c Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 17:52:29 +0530 Subject: [PATCH 12/58] Rename A95-SNI-setting-and-SNI-SAN-validation.md to A98-SNI-setting-and-SNI-SAN-validation.md --- ...SAN-validation.md => A98-SNI-setting-and-SNI-SAN-validation.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename A95-SNI-setting-and-SNI-SAN-validation.md => A98-SNI-setting-and-SNI-SAN-validation.md (100%) diff --git a/A95-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md similarity index 100% rename from A95-SNI-setting-and-SNI-SAN-validation.md rename to A98-SNI-setting-and-SNI-SAN-validation.md From b1b762ba9a2bcf02a438eb9b3728b166c72fc55b Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 25 Jul 2025 18:38:00 +0530 Subject: [PATCH 13/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index df0896fe9..df35cb212 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -102,7 +102,8 @@ the [`match_subject_alt_names`][match_subject_alt_names] if set. The SNI to chec aggainst will be made available to the code performing SAN validation in a language dependent way, for example in Java, the SNI used will be set in the `XdsX509TrustManager` that performs the SAN validation and is set in the `SslContext` -used for the handshake. +used for the handshake, and this SNI will be passed on from the `SslContextProvider` +to the `XdsX509TrustManager` constructor. [A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 From 01735fcb32b912e36338c888d3823e815b59cc35 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 13:52:41 +0530 Subject: [PATCH 14/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index df35cb212..a889373fe 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -74,7 +74,15 @@ sent. As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or is put in sub-channel attribute wrapped in a -`SslContextProvider`, depending on the language. This mechanism +`SslContextProvider`, depending on the language. So far the same +information has been used for creating the Ssl connection for all +the subchannels in the channel so there was a single instance of +the provider of this Tls/Ssl context, instantiated by the LB policy +and made available as a subchannel attribute to b + +1. + +This mechanism will be augmented in the ClusterImpl LB policy to also add the information about SNI if any that needs to be used during the Tls handshake. To make this decision, the the LB policy will From 44e755025da3ad86f2701af9c92866a551fa8e0e Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 14:01:36 +0530 Subject: [PATCH 15/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index a889373fe..826ce4c7b 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -76,9 +76,11 @@ As mentioned in [A29 implementation details][A29_impl-details] the channel arguments or is put in sub-channel attribute wrapped in a `SslContextProvider`, depending on the language. So far the same information has been used for creating the Ssl connection for all -the subchannels in the channel so there was a single instance of +the subchannels in the channel so it sufficed to have a single instance of the provider of this Tls/Ssl context, instantiated by the LB policy -and made available as a subchannel attribute to b +and set in the ClusterImpl LB policy helper, which then set this +provider object as an address attribute of the subchannels created +by this helper. 1. From 321065362d7f262ebdb18acb100cab82eb41c521 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 14:13:36 +0530 Subject: [PATCH 16/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 826ce4c7b..0753b9aee 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -79,8 +79,15 @@ information has been used for creating the Ssl connection for all the subchannels in the channel so it sufficed to have a single instance of the provider of this Tls/Ssl context, instantiated by the LB policy and set in the ClusterImpl LB policy helper, which then set this -provider object as an address attribute of the subchannels created -by this helper. +provider object as an address attribute of all the subchannels created +by this helper. For setting the SNI to the hostname, a separate instance +of the provider needs to be created for each subchannel, augmented with +the hostname to use for the subchannel. So the creation of this provider +will have to move from the LB policy's accepting addresses to the LB policy +helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` +if any, is either already avaiiable to the provider via the TlsContext, or if +it doesn't hold the whole object in a langguage implementation, it will need to +have an additional field to hold the SNI to use for all the endpoints in the cluster. 1. From a8dd3afd9d26bb14796a808df8af427fd23f435c Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 15:15:54 +0530 Subject: [PATCH 17/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 0753b9aee..ff139e609 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -76,7 +76,7 @@ As mentioned in [A29 implementation details][A29_impl-details] the channel arguments or is put in sub-channel attribute wrapped in a `SslContextProvider`, depending on the language. So far the same information has been used for creating the Ssl connection for all -the subchannels in the channel so it sufficed to have a single instance of +the subchannels in the cluster so it sufficed to have a single instance of the provider of this Tls/Ssl context, instantiated by the LB policy and set in the ClusterImpl LB policy helper, which then set this provider object as an address attribute of all the subchannels created @@ -85,21 +85,9 @@ of the provider needs to be created for each subchannel, augmented with the hostname to use for the subchannel. So the creation of this provider will have to move from the LB policy's accepting addresses to the LB policy helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` -if any, is either already avaiiable to the provider via the TlsContext, or if -it doesn't hold the whole object in a langguage implementation, it will need to -have an additional field to hold the SNI to use for all the endpoints in the cluster. - -1. - -This mechanism -will be augmented in the ClusterImpl LB policy to also add the -information about SNI if any that needs to be used during the -Tls handshake. To make this decision, the the LB policy will -make use of [UpstreamTlsContext.SNI][UTC_SNI] and the hostname -from `CdsUpdate` that is passed down by the Cds LB policy to the -ClusterImpl LB policy. In a language implementation dependent -way, this SNI value to set will be passed on to the Tls handling -code. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` +would already be available to this provider from the parsed Cluster resource. +In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling +code from this Tls context provider. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed based on the cert store to use as indicated by `UpstreamTlsContext`. The SNI value to use in the `SslContextProvider` will be made From f3eef8432893f8e96de15084f638ece8fe9378c2 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 15:58:09 +0530 Subject: [PATCH 18/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index ff139e609..77234dcb7 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -69,8 +69,8 @@ sent. [A29]: A29-xds-tls-security.md [A81]: A81-xds-authority-rewriting.md -### xds_cluster_impl LB Policy Changes -#### Setting SNI +### Setting SNI +#### xds_cluster_impl LB Policy Changes As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or is put in sub-channel attribute wrapped in a @@ -86,8 +86,10 @@ the hostname to use for the subchannel. So the creation of this provider will have to move from the LB policy's accepting addresses to the LB policy helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` would already be available to this provider from the parsed Cluster resource. + +#### Tls handshake time changes In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling -code from this Tls context provider. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` +code from the Tls context provider set as a subchannel attribute. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed based on the cert store to use as indicated by `UpstreamTlsContext`. The SNI value to use in the `SslContextProvider` will be made @@ -97,7 +99,7 @@ creating the `SslEngine` for the transport. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 -#### SAN SNI validation +### SAN SNI validation The server certificate validation described in [A29 SAN matching][A29_SAN-matching] matches the Subject Alternative Names specified in the server certificate against [`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. @@ -114,6 +116,9 @@ to the `XdsX509TrustManager` constructor. [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 -#### Temporary environment variable protection +#### Behavior when SNI is not indicated in UpstreamTlsContext +When `UpstreamTlsContext` has neither of `SNI` and `auto_host_sni` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. + +### Temporary environment variable protection Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` env var. The env var guard will be removed once the feature passes interop tests. From 9009682190f64459ca25a0569e3de7de8d43c682 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 16:09:29 +0530 Subject: [PATCH 19/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 77234dcb7..6a707f04f 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -47,7 +47,7 @@ in the CDS update. 1. If [UpstreamTlsContext][UTC] specifies the SNI to use, then it will be used. -2. If [UpstreamTlsContext][UTC] specifies `auto_host_sni`, then +2. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the logical DNS name for DNS clusters or the endponit hostname for EDS clusters, as in the case of the hostname useed for authority @@ -117,7 +117,7 @@ to the `XdsX509TrustManager` constructor. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 #### Behavior when SNI is not indicated in UpstreamTlsContext -When `UpstreamTlsContext` has neither of `SNI` and `auto_host_sni` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. +When `UpstreamTlsContext` has neither of `SNI` and `auto_sni_host` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. ### Temporary environment variable protection Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` From 116f6ca9c84a3d27c195ff9f394c43d0390a800f Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 18:17:57 +0530 Subject: [PATCH 20/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 6a707f04f..b15d0b35f 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -87,13 +87,18 @@ will have to move from the LB policy's accepting addresses to the LB policy helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` would already be available to this provider from the parsed Cluster resource. +##### Performance optimization +If several or all of the endpoints in a cluster have the same hostname, then +the corresponding Ssl provider instances all hold the same information, and this +can lead to too many unnecessary objects created when not really necessary. To +avoid this, the LB helper will maintain a map of hostname to Ssl provider instances +and reuse the same instance if the hostname to use is the same. + #### Tls handshake time changes In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling -code from the Tls context provider set as a subchannel attribute. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` -that is made available the `SslContext` dynamically constructed -based on the cert store to use as indicated by `UpstreamTlsContext`. -The SNI value to use in the `SslContextProvider` will be made -available to the `ProtocolNegotiators.ClientTlsHandler` to use when +code from the Tls context provider set as a subchannel attribute. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed +based on the cert store to use as indicated by `UpstreamTlsContext`. The SNI value to use from the +`SslContextProvider` will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when creating the `SslEngine` for the transport. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details From 73780e541a173ad5d679f72fc831361b961a7602 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 28 Jul 2025 18:18:39 +0530 Subject: [PATCH 21/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index b15d0b35f..19e12f154 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -4,7 +4,7 @@ A98: xDS-Based setting SNI and server certificate SAN validation * Approver: [Eric Anderson](https://github.com/ejona86) * Status: Draft * Implemented in: -* Last updated: 2025-07-25 +* Last updated: 2025-07-28 ## Abstract From 7e3c705312a7a99342308bc123ef3eb42017b582 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Tue, 29 Jul 2025 17:03:20 +0530 Subject: [PATCH 22/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 19e12f154..cceab6560 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -74,7 +74,7 @@ sent. As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or is put in sub-channel attribute wrapped in a -`SslContextProvider`, depending on the language. So far the same +`SslContextProviderSupplier`, depending on the language. So far the same information has been used for creating the Ssl connection for all the subchannels in the cluster so it sufficed to have a single instance of the provider of this Tls/Ssl context, instantiated by the LB policy @@ -98,7 +98,7 @@ and reuse the same instance if the hostname to use is the same. In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling code from the Tls context provider set as a subchannel attribute. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed based on the cert store to use as indicated by `UpstreamTlsContext`. The SNI value to use from the -`SslContextProvider` will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when +`SslContextProviderSupplier` will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when creating the `SslEngine` for the transport. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details @@ -110,12 +110,18 @@ matches the Subject Alternative Names specified in the server certificate agains [`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], matching will be performed against the SNI that was used by the client, and this validation will replace -the [`match_subject_alt_names`][match_subject_alt_names] if set. The SNI to check -aggainst will be made available to the code performing SAN validation in a -language dependent way, for example in Java, the SNI used will be set in the -`XdsX509TrustManager` that performs the SAN validation and is set in the `SslContext` -used for the handshake, and this SNI will be passed on from the `SslContextProvider` -to the `XdsX509TrustManager` constructor. +the [`match_subject_alt_names`][match_subject_alt_names] if set. This verification occurs +in the TrustManager of the SslContext which is created using the cert store indicated by +`CertificateValidationContext` in `UpstreamTlsContext` which is either a managed cert store +or the system root cert store. + +#### Caching for the SslContext +The `SslContextProviderSupplier` creates a provider for the +client `SslContext` and today maintains a cache of `UpstreamTlsContext` to the client `SslContext` +provider instances. For the SNI requirement, the `TrustManager` in the `SslContext` needs to +be aware of the SNI to validate the SAN against, so a different `TrustManager` instance needs +to be created for each SNI to use for the same `UpstreamTlsContext`, so this cache's key will +need to be enhanced to be to hold the SNI as well. [A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 From 86273ceceea7a83a2d02173704104b034eac769a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Tue, 29 Jul 2025 17:04:50 +0530 Subject: [PATCH 23/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index cceab6560..240db9cb4 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -87,12 +87,12 @@ will have to move from the LB policy's accepting addresses to the LB policy helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` would already be available to this provider from the parsed Cluster resource. -##### Performance optimization +##### Caching If several or all of the endpoints in a cluster have the same hostname, then the corresponding Ssl provider instances all hold the same information, and this can lead to too many unnecessary objects created when not really necessary. To -avoid this, the LB helper will maintain a map of hostname to Ssl provider instances -and reuse the same instance if the hostname to use is the same. +avoid this, the LB helper will maintain a map of hostname to `SslContextProviderSupplier` +instancesand reuse the same instance if the hostname to use is the same. #### Tls handshake time changes In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling From 8131e6bda4fb05b28bba4cb6bc0994c1bda5753f Mon Sep 17 00:00:00 2001 From: Kannan J Date: Tue, 29 Jul 2025 17:09:02 +0530 Subject: [PATCH 24/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 240db9cb4..98e2b05e2 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -116,12 +116,15 @@ in the TrustManager of the SslContext which is created using the cert store indi or the system root cert store. #### Caching for the SslContext -The `SslContextProviderSupplier` creates a provider for the -client `SslContext` and today maintains a cache of `UpstreamTlsContext` to the client `SslContext` -provider instances. For the SNI requirement, the `TrustManager` in the `SslContext` needs to +The `SslContextProviderSupplier` (named so because it supplies both client and server +SslContext providers) creates a provider for the client `SslContext` and today +maintains a cache of `UpstreamTlsContext` to the client `SslContext` provider instances. +For the SNI requirement, the `TrustManager` in the `SslContext` needs to be aware of the SNI to validate the SAN against, so a different `TrustManager` instance needs to be created for each SNI to use for the same `UpstreamTlsContext`, so this cache's key will -need to be enhanced to be to hold the SNI as well. +need to be enhanced to be to hold the SNI as well, and the client +`SslContext` provider for a particular key will create a `TrustManager` instance that takes the +SNI to validate the SANs against and set it in the `SslContext` it provides. [A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 From 44949ed9175d56f512228f4cfa5f2a83032b45ec Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 4 Aug 2025 17:51:10 +0530 Subject: [PATCH 25/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 36 +++++++---------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 98e2b05e2..11e4d9fe2 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -70,35 +70,19 @@ sent. [A81]: A81-xds-authority-rewriting.md ### Setting SNI -#### xds_cluster_impl LB Policy Changes +#### Tls handshake time changes As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or is put in sub-channel attribute wrapped in a -`SslContextProviderSupplier`, depending on the language. So far the same -information has been used for creating the Ssl connection for all -the subchannels in the cluster so it sufficed to have a single instance of -the provider of this Tls/Ssl context, instantiated by the LB policy -and set in the ClusterImpl LB policy helper, which then set this -provider object as an address attribute of all the subchannels created -by this helper. For setting the SNI to the hostname, a separate instance -of the provider needs to be created for each subchannel, augmented with -the hostname to use for the subchannel. So the creation of this provider -will have to move from the LB policy's accepting addresses to the LB policy -helper creating subchannel when invoed by the child LB policy. The `UpstreamTlsContext.SNI` -would already be available to this provider from the parsed Cluster resource. - -##### Caching -If several or all of the endpoints in a cluster have the same hostname, then -the corresponding Ssl provider instances all hold the same information, and this -can lead to too many unnecessary objects created when not really necessary. To -avoid this, the LB helper will maintain a map of hostname to `SslContextProviderSupplier` -instancesand reuse the same instance if the hostname to use is the same. - -#### Tls handshake time changes -In a language implementation dependent way, this SNI value to set will be passed on to the Tls handling -code from the Tls context provider set as a subchannel attribute. For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is made available the `SslContext` dynamically constructed -based on the cert store to use as indicated by `UpstreamTlsContext`. The SNI value to use from the -`SslContextProviderSupplier` will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when +`SslContextProviderSupplier`, depending on the language. The `UpstreamTlsContext.SNI` +would already be available to this provider supplier from the parsed Cluster resource. +At the time of Tls protocol negotiation, when this provider supplier is +invoked to set the SslContext, the hostname from the channel attributes +also will be passed, to determine the SNI to be set for the Tls handshake. +For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is +made available the `SslContext` dynamically constructed based on the cert store to use +as indicated by `UpstreamTlsContext`. The SNI value to use from the `SslContextProviderSupplier` +will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when creating the `SslEngine` for the transport. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details From 2ac9c4af551a0ffc39a9dafea939b2a3199c522a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 4 Aug 2025 18:15:53 +0530 Subject: [PATCH 26/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 32 +++++++++++------------ 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 11e4d9fe2..537a14aca 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -20,47 +20,45 @@ via Server Name Indication (SNI). When using `XdsChannelCredentials` for a chann to be configured by the xDS server with what value to send for SNI and the gRPC client should use it for the Tls handshake. -In [A29][A29] for TLS security in xDS-managed connections, it -proposed that the `SNI` field from [UpstreamTlsContext.SNI][UTC_SNI] -would be ignored. In proposal seeks to start using this and other fields -for setting the SNI by the gRPC client. +In [A29][A29] for TLS security in xDS-managed connections, the `sni` field from [UpstreamTlsContext.sni][UTC_SNI] +was ignored. -When using `XdsChannelCredentials` for the transport, hostname validation -is turned off and instead SAN matching is performed against [UpstreamTlsContext.match_subject_alt_names][match_subject_alt_names]. -This proposal adds checking of SAN against the SNI provided by the client as well. +When using `XdsChannelCredentials` for the channel, hostname validation +is turned off and instead SAN matching is performed against [UpstreamTlsContext.match_subject_alt_names][match_subject_alt_names] +instead of a typical hostname. This proposal adds SAN matching for the same name as the client used for SNI. For an overview of securing connections in the envoy proxy using SNI and SAN validation, see [envoy-SNI]. [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 [A29]: A29-xds-tls-security.md -[envoy-SNI]: https://www.envoyproxy.io/docs/envoy/latest/_sources/start/quick-start/securing.rst.txt +[envoy-SNI]: https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/securing [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 ## Proposal This proposal has two parts: * Setting SNI -xDS-managed gRPC clients will set SNI for the Tls handshake for -Tls connections using the fields from [UpstreamTlsContext][UTC] -in the CDS update. +When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for +Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. -1. If [UpstreamTlsContext][UTC] specifies the SNI to use, then +1. If `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. 2. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the logical -DNS name for DNS clusters or the endponit hostname for EDS -clusters, as in the case of the hostname useed for authority -rewriting [Ar 81-hostname][A81-hostname]. +DNS name for DNS clusters or the endpoint hostname for EDS +clusters, as in the case of the hostname used for [authority +rewriting][A81-hostname]. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 [A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md?plain=1#L85 * Server SAN validation against SNI used -If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC] +If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] gRPC client will perform validation for a DNS SAN matching the SNI value -sent. +sent. The normal matching when using `TlsCredentials' for the channel +allows other SAN types, but only the DNS type will be checked here. ### Related Proposals: * [gRFC A29: xDS-Based Security for gRPC Clients and Servers][A29] From 695e989deeba2b791cb73aa19b3a607f858a48e6 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 4 Aug 2025 18:46:02 +0530 Subject: [PATCH 27/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 537a14aca..6ab6193f4 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -38,6 +38,7 @@ and SAN validation, see [envoy-SNI]. ## Proposal This proposal has two parts: * Setting SNI + When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. From 0d9eeb81cedfa12dd56bf8612f8025e7e6610e90 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Wed, 6 Aug 2025 23:52:12 +0530 Subject: [PATCH 28/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 26 ++++++++++------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 6ab6193f4..14abd6186 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -37,15 +37,13 @@ and SAN validation, see [envoy-SNI]. ## Proposal This proposal has two parts: -* Setting SNI - -When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for +1. Setting SNI: When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. -1. If `UpstreamTlsContext.sni` specifies the SNI to use, then + i. If `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. -2. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then + ii. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the logical DNS name for DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority @@ -54,9 +52,7 @@ rewriting][A81-hostname]. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 [A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md?plain=1#L85 -* Server SAN validation against SNI used - -If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] +2. Server SAN validation against SNI used: If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] gRPC client will perform validation for a DNS SAN matching the SNI value sent. The normal matching when using `TlsCredentials' for the channel allows other SAN types, but only the DNS type will be checked here. @@ -76,13 +72,13 @@ channel arguments or is put in sub-channel attribute wrapped in a `SslContextProviderSupplier`, depending on the language. The `UpstreamTlsContext.SNI` would already be available to this provider supplier from the parsed Cluster resource. At the time of Tls protocol negotiation, when this provider supplier is -invoked to set the SslContext, the hostname from the channel attributes -also will be passed, to determine the SNI to be set for the Tls handshake. -For example, in Java, there is a `ProtocolNegotiators.ClientTlsHandler` that is -made available the `SslContext` dynamically constructed based on the cert store to use -as indicated by `UpstreamTlsContext`. The SNI value to use from the `SslContextProviderSupplier` -will be made available to the `ProtocolNegotiators.ClientTlsHandler` to use when -creating the `SslEngine` for the transport. +used to invoked to set the SslContext, the hostname from the channel attributes +also will be passed now, to determine the SNI to be set for the Tls handshake. +For example, in Java, at protocol negotiation time the `SslContextProviderSupplier` is given +a callback to be invoked with the `SslContext` when the client Ssl Provider instantiated by +this supplier has the `SslContext` ready. This callback will now also be passed the SNI +taken from the subchannel attributes. This value along with the `UpstreamTlsContext` available +in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 From 93985b1a86f0c07863d230ddb722d04d56a6c5a5 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:04:54 +0530 Subject: [PATCH 29/58] Update A98-SNI-setting-and-SNI-SAN-validation.md Co-authored-by: Antoine Tollenaere --- A98-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 14abd6186..b76be3a88 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -110,7 +110,7 @@ SNI to validate the SANs against and set it in the `SslContext` it provides. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 #### Behavior when SNI is not indicated in UpstreamTlsContext -When `UpstreamTlsContext` has neither of `SNI` and `auto_sni_host` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. +When `UpstreamTlsContext` has neither of `SNI` nor `auto_sni_host` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. ### Temporary environment variable protection Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` From bc24aae85e967b41ac84fd321fc366c9fe9c5b0a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:21:28 +0530 Subject: [PATCH 30/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index b76be3a88..18989cdf5 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -38,17 +38,17 @@ and SAN validation, see [envoy-SNI]. ## Proposal This proposal has two parts: 1. Setting SNI: When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for -Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. +Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. - i. If `UpstreamTlsContext.sni` specifies the SNI to use, then -it will be used. - - ii. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then + i. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the logical DNS name for DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. + ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then +it will be used. + [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 [A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md?plain=1#L85 From 5d818fd00e9cd4f5ab77c4d41eb8d97f8eb52a74 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:29:50 +0530 Subject: [PATCH 31/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 33 +++++++++++++---------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 18989cdf5..5b62849c5 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -50,7 +50,7 @@ rewriting][A81-hostname]. it will be used. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 -[A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md?plain=1#L85 +[A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md#xds-resource-validation 2. Server SAN validation against SNI used: If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] gRPC client will perform validation for a DNS SAN matching the SNI value @@ -66,19 +66,24 @@ allows other SAN types, but only the DNS type will be checked here. ### Setting SNI #### Tls handshake time changes -As mentioned in [A29 implementation details][A29_impl-details] the -`UpstreamTlsContext` is either passed down to child policies via -channel arguments or is put in sub-channel attribute wrapped in a -`SslContextProviderSupplier`, depending on the language. The `UpstreamTlsContext.SNI` -would already be available to this provider supplier from the parsed Cluster resource. -At the time of Tls protocol negotiation, when this provider supplier is -used to invoked to set the SslContext, the hostname from the channel attributes -also will be passed now, to determine the SNI to be set for the Tls handshake. -For example, in Java, at protocol negotiation time the `SslContextProviderSupplier` is given -a callback to be invoked with the `SslContext` when the client Ssl Provider instantiated by -this supplier has the `SslContext` ready. This callback will now also be passed the SNI -taken from the subchannel attributes. This value along with the `UpstreamTlsContext` available -in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. +As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either +passed down to child policies via channel arguments or a similar mechanism, depending on the language, +and the SslContext is instantiated using the truststore location indicated by the `UpstreamTlsContext`. +This SslContext is then used to initiate the Tls handshake for the transport and this is when the SNI is sent +for the `ClientHello` frame of the handshake. To determine the SNI, we need both the `UpstreamTlsContext` and +the hostname for the endpoint. The hostname attribute is already stored in the subchannel wrapper by the +xds_cluster_impl policy when its child policy creates a subchannel. Once the `SslContext` is available during the +Tls handshake phase of the transport creation (the creation of which depends on the choice of the certificate provider +infra to use as indicated by the `UpstreamTlsContext`), the fields from `UpstreamTlsContext` and the hostname +from the channel attributes will be used to determine the SNI to set for the handshake. + +##### Language specific example +As an example, in Java, the ClusterImpl LB policy creates the `SslContextProviderSuppler` wrapping the +`UpstreamTlsContext` and puts it in the subchannel wrapper when its child policy creates a subchannel. At the time of Tls protocol negotiation +for the subchannel, the hostname from the channel attributes also should be passed to this provider supplier to determine the SNI to be set for +the Tls handshake. The hostname will be set in the callback object that is given to the `SslContextProviderSupplier`, to be invoked with the +`SslContext` when the client Ssl Provider instantiated by this supplier has the `SslContext` available. This value along with the +`UpstreamTlsContext` available in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. [A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 From d74f615bfd21ffca8a97fcd325e98f753a80d572 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:33:00 +0530 Subject: [PATCH 32/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 5b62849c5..226952b2d 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -110,7 +110,7 @@ need to be enhanced to be to hold the SNI as well, `SslContext` provider for a particular key will create a `TrustManager` instance that takes the SNI to validate the SANs against and set it in the `SslContext` it provides. -[A29_SAN-matching]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks +[A29_SAN-matching]: A29-xds-tls-security.md#server-authorization-aka-subject-alt-name-checks [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 From fae9bde40ca17efdc1ff5be21e26333189b9e8af Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:35:01 +0530 Subject: [PATCH 33/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 226952b2d..1f0908e50 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -64,8 +64,7 @@ allows other SAN types, but only the DNS type will be checked here. [A29]: A29-xds-tls-security.md [A81]: A81-xds-authority-rewriting.md -### Setting SNI -#### Tls handshake time changes +### Setting SNI during Tls handshake As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or a similar mechanism, depending on the language, and the SslContext is instantiated using the truststore location indicated by the `UpstreamTlsContext`. From 620f8d3c44a6b664dbb41e66d5ef7ae07180304e Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:35:58 +0530 Subject: [PATCH 34/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index 1f0908e50..a4e241f85 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -54,7 +54,7 @@ it will be used. 2. Server SAN validation against SNI used: If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] gRPC client will perform validation for a DNS SAN matching the SNI value -sent. The normal matching when using `TlsCredentials' for the channel +sent. The normal matching when using `TlsCredentials` for the channel allows other SAN types, but only the DNS type will be checked here. ### Related Proposals: From c9f6d02d092944e9d9f230654463e81ba09273ce Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:37:46 +0530 Subject: [PATCH 35/58] Update A98-SNI-setting-and-SNI-SAN-validation.md --- A98-SNI-setting-and-SNI-SAN-validation.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A98-SNI-setting-and-SNI-SAN-validation.md index a4e241f85..cbecb9332 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A98-SNI-setting-and-SNI-SAN-validation.md @@ -40,11 +40,8 @@ This proposal has two parts: 1. Setting SNI: When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. - i. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then -SNI will be set to the hostname, which is either the logical -DNS name for DNS clusters or the endpoint hostname for EDS -clusters, as in the case of the hostname used for [authority -rewriting][A81-hostname]. + i. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the DNS name for +logical DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. From a4072aa7281d8d8a6d3036bba6bcbe8d6cab6f81 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:39:15 +0530 Subject: [PATCH 36/58] Update and rename A98-SNI-setting-and-SNI-SAN-validation.md to A101-SNI-setting-and-SNI-SAN-validation.md --- ...-validation.md => A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename A98-SNI-setting-and-SNI-SAN-validation.md => A101-SNI-setting-and-SNI-SAN-validation.md (99%) diff --git a/A98-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md similarity index 99% rename from A98-SNI-setting-and-SNI-SAN-validation.md rename to A101-SNI-setting-and-SNI-SAN-validation.md index cbecb9332..f51fb75b2 100644 --- a/A98-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -1,4 +1,4 @@ -A98: xDS-Based setting SNI and server certificate SAN validation +A101: xDS-Based setting SNI and server certificate SAN validation ---- * Author: [Kannan Jayaprakasam](https://github.com/kannanjgithub) * Approver: [Eric Anderson](https://github.com/ejona86) From 94c8792f0da123a0a81b1ac661658ad0add85e68 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:44:38 +0530 Subject: [PATCH 37/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index f51fb75b2..58102c58d 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -113,6 +113,9 @@ SNI to validate the SANs against and set it in the `SslContext` it provides. #### Behavior when SNI is not indicated in UpstreamTlsContext When `UpstreamTlsContext` has neither of `SNI` nor `auto_sni_host` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. +#### Validation +The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters, similar to Envoy. + ### Temporary environment variable protection Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` env var. The env var guard will be removed once the feature passes interop tests. From 60cf9fc65c8fe2c03331d71fe6f522428697ac01 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:45:47 +0530 Subject: [PATCH 38/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 58102c58d..07f2759c6 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -40,7 +40,7 @@ This proposal has two parts: 1. Setting SNI: When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. - i. If [UpstreamTlsContext][UTC] specifies `auto_sni_host`, then SNI will be set to the hostname, which is either the DNS name for + i. If [UpstreamTlsContext][UTC] specifies `auto_host_sni`, then SNI will be set to the hostname, which is either the DNS name for logical DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then From 2d80a41445c84ba4e874ef4f2191944838eee572 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Thu, 21 Aug 2025 22:57:08 +0530 Subject: [PATCH 39/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 07f2759c6..84e39dea6 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -43,8 +43,9 @@ Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS updat i. If [UpstreamTlsContext][UTC] specifies `auto_host_sni`, then SNI will be set to the hostname, which is either the DNS name for logical DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. - ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then -it will be used. + ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. + + iii. Otherwise no SNI will be set for the Tls handshake. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 [A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md#xds-resource-validation From cc52390a5e172a3ada4c5f63321845edb2e5697a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 15:34:05 +0530 Subject: [PATCH 40/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 84e39dea6..7508fa921 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -48,7 +48,7 @@ logical DNS clusters or the endpoint hostname for EDS clusters, as in the case o iii. Otherwise no SNI will be set for the Tls handshake. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 -[A81-hostname]: https://github.com/grpc/proposal/blob/4f833c5774e71e94534f72b94ee1b9763ec58516/A81-xds-authority-rewriting.md#xds-resource-validation +[A81-hostname]: A81-xds-authority-rewriting.md#xds-resource-validation 2. Server SAN validation against SNI used: If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] gRPC client will perform validation for a DNS SAN matching the SNI value From a497cfa95a9f308b33e239ed50894e5ecb6d93e2 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 15:37:04 +0530 Subject: [PATCH 41/58] Update A29-xds-tls-security.md --- A29-xds-tls-security.md | 1 + 1 file changed, 1 insertion(+) diff --git a/A29-xds-tls-security.md b/A29-xds-tls-security.md index f4b16c281..4c08cc6bc 100644 --- a/A29-xds-tls-security.md +++ b/A29-xds-tls-security.md @@ -6,6 +6,7 @@ A29: xDS-Based Security for gRPC Clients and Servers * Implemented in: C-core, Java, and Go * Last updated: 2021-08-30 * Discussion at: https://groups.google.com/g/grpc-io/c/4IwVLPeTAe4/m/ng9w3D0XBgAJ +* Updated by: [A101: xDS-Based setting SNI and server certificate SAN validation](A101-SNI-setting-and-SNI-SAN-validation.md) ## Abstract From 995111e424bb9b297ff386940ea13907365eb180 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 16:15:50 +0530 Subject: [PATCH 42/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 7508fa921..670d6676d 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -82,7 +82,7 @@ the Tls handshake. The hostname will be set in the callback object that is given `SslContext` when the client Ssl Provider instantiated by this supplier has the `SslContext` available. This value along with the `UpstreamTlsContext` available in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. -[A29_impl-details]: https://github.com/grpc/proposal/blob/master/A29-xds-tls-security.md#implementation-details +[A29_impl-details]: A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 ### SAN SNI validation From a010ace5d38042cf7be59f2108fc005ab672c19d Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 18:36:34 +0530 Subject: [PATCH 43/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 670d6676d..228ef5397 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -40,12 +40,12 @@ This proposal has two parts: 1. Setting SNI: When using `XdsChannelCredentials` for the channel, gRPC clients will set SNI for the Tls handshake for Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS update. - i. If [UpstreamTlsContext][UTC] specifies `auto_host_sni`, then SNI will be set to the hostname, which is either the DNS name for -logical DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. + i. If [UpstreamTlsContext][UTC] specifies `auto_host_sni` and the hostname is available, then SNI will be set to the hostname. The hostname + is either the DNS name for logical DNS clusters or the endpoint hostname for EDS clusters, as in the case of the hostname used for [authority rewriting][A81-hostname]. - ii. If `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. + ii. Else, if `UpstreamTlsContext.sni` specifies the SNI to use, then it will be used. - iii. Otherwise no SNI will be set for the Tls handshake. + iii. Else, no SNI will be set for the Tls handshake. [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 [A81-hostname]: A81-xds-authority-rewriting.md#xds-resource-validation From c2b7f8ae457a79528e3fae8ea9f3c7def976aa73 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 19:35:05 +0530 Subject: [PATCH 44/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 23 +++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 228ef5397..f50cc0306 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -64,15 +64,20 @@ allows other SAN types, but only the DNS type will be checked here. ### Setting SNI during Tls handshake As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either -passed down to child policies via channel arguments or a similar mechanism, depending on the language, -and the SslContext is instantiated using the truststore location indicated by the `UpstreamTlsContext`. -This SslContext is then used to initiate the Tls handshake for the transport and this is when the SNI is sent -for the `ClientHello` frame of the handshake. To determine the SNI, we need both the `UpstreamTlsContext` and -the hostname for the endpoint. The hostname attribute is already stored in the subchannel wrapper by the -xds_cluster_impl policy when its child policy creates a subchannel. Once the `SslContext` is available during the -Tls handshake phase of the transport creation (the creation of which depends on the choice of the certificate provider -infra to use as indicated by the `UpstreamTlsContext`), the fields from `UpstreamTlsContext` and the hostname -from the channel attributes will be used to determine the SNI to set for the handshake. +passed down to child policies via channel arguments or a similar mechanism, depending on the language. +[A29 implementation details][A29_impl-details] also talks about a `CertificateProvider` object that represents +a plugin that provides the required certificates and keys to the gRPC application. When Tls handshake is +initiated for a channel that is using `XdsCredentials`, this `CertificateProvider` object is used to +provide the certs and trust roots for establishing the secure connection. During this handshake we need +to set the SNI to use for the `ClientHello` frame of the handshake. To determine the SNI, we need both the +`UpstreamTlsContext` and the hostname for the endpoint. +The `UpstreamTlsContext` comes via the xds cluster configuration, and the xds_cluster_impl policy sets this +`CertificateProvider` into the subchannel wrapper when its child LB policy creates the subchannel. It also +stores the hostname attribute of the endpoint in the subchannel wrapper. To determine the SNI the parsed +information from `UpstreamTlsContext.sni` and `UpstreamTlsContext.auto_host_sni` will also be set into the +`CertificateProvider`. When the Tls handling code uses the certs and trust roots from the `CertificateProvider` +to establish the connection, it will also now determine the SNI to set based on the parsed sni related fields +available in the `CertificateProvider` and also the hostname available in the subchannel attributes. ##### Language specific example As an example, in Java, the ClusterImpl LB policy creates the `SslContextProviderSuppler` wrapping the From c84b8a43307ac301e8cc9059aa904a203e34b1d3 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 20:01:21 +0530 Subject: [PATCH 45/58] Update A101-SNI-setting-and-SNI-SAN-validation.md Make the SAN validation non-Java specific also. --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index f50cc0306..f256ff47a 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -97,7 +97,7 @@ matches the Subject Alternative Names specified in the server certificate agains If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], matching will be performed against the SNI that was used by the client, and this validation will replace the [`match_subject_alt_names`][match_subject_alt_names] if set. This verification occurs -in the TrustManager of the SslContext which is created using the cert store indicated by +in the TrustManager created by the `CertificateProvider` using the cert store indicated by `CertificateValidationContext` in `UpstreamTlsContext` which is either a managed cert store or the system root cert store. From 6cb765a95df59a09bfccdfde8c92742c64b9aed1 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 25 Aug 2025 20:04:46 +0530 Subject: [PATCH 46/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index f256ff47a..ec3cca1cd 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -101,7 +101,7 @@ in the TrustManager created by the `CertificateProvider` using the cert store in `CertificateValidationContext` in `UpstreamTlsContext` which is either a managed cert store or the system root cert store. -#### Caching for the SslContext +#### (Java language specific) Caching for the SslContext The `SslContextProviderSupplier` (named so because it supplies both client and server SslContext providers) creates a provider for the client `SslContext` and today maintains a cache of `UpstreamTlsContext` to the client `SslContext` provider instances. From a05fcb80ad112bb66b316fc479ed050e817a7a58 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 12:36:05 +0530 Subject: [PATCH 47/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index ec3cca1cd..9600e09fd 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -70,7 +70,7 @@ a plugin that provides the required certificates and keys to the gRPC applicatio initiated for a channel that is using `XdsCredentials`, this `CertificateProvider` object is used to provide the certs and trust roots for establishing the secure connection. During this handshake we need to set the SNI to use for the `ClientHello` frame of the handshake. To determine the SNI, we need both the -`UpstreamTlsContext` and the hostname for the endpoint. +SNI related fields from the parsed `UpstreamTlsContext` and the hostname for the endpoint. The `UpstreamTlsContext` comes via the xds cluster configuration, and the xds_cluster_impl policy sets this `CertificateProvider` into the subchannel wrapper when its child LB policy creates the subchannel. It also stores the hostname attribute of the endpoint in the subchannel wrapper. To determine the SNI the parsed From 8f6f5f1a5ce2e473ce153ec764d9d969c4d6f648 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 12:52:48 +0530 Subject: [PATCH 48/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 9600e09fd..b704bd1ab 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -71,18 +71,18 @@ initiated for a channel that is using `XdsCredentials`, this `CertificateProvide provide the certs and trust roots for establishing the secure connection. During this handshake we need to set the SNI to use for the `ClientHello` frame of the handshake. To determine the SNI, we need both the SNI related fields from the parsed `UpstreamTlsContext` and the hostname for the endpoint. -The `UpstreamTlsContext` comes via the xds cluster configuration, and the xds_cluster_impl policy sets this -`CertificateProvider` into the subchannel wrapper when its child LB policy creates the subchannel. It also -stores the hostname attribute of the endpoint in the subchannel wrapper. To determine the SNI the parsed -information from `UpstreamTlsContext.sni` and `UpstreamTlsContext.auto_host_sni` will also be set into the -`CertificateProvider`. When the Tls handling code uses the certs and trust roots from the `CertificateProvider` +To determine the SNI `UpstreamTlsContext.sni` and `UpstreamTlsContext.auto_host_sni` from the parsed +cluster resource will also be set into the `CertificateProvider` by the xds_cluster_impl policy. +When the Tls handling code uses the certs and trust roots from the `CertificateProvider` to establish the connection, it will also now determine the SNI to set based on the parsed sni related fields -available in the `CertificateProvider` and also the hostname available in the subchannel attributes. +available in the `CertificateProvider` and the hostname in the endpoint attributes. + +[A81_xds_resource_validation]: A81-xds-authority-rewriting.md#xds-resource-validation ##### Language specific example As an example, in Java, the ClusterImpl LB policy creates the `SslContextProviderSuppler` wrapping the `UpstreamTlsContext` and puts it in the subchannel wrapper when its child policy creates a subchannel. At the time of Tls protocol negotiation -for the subchannel, the hostname from the channel attributes also should be passed to this provider supplier to determine the SNI to be set for +for the subchannel, the hostname from the endpoint address attributes also should be passed to this provider supplier to determine the SNI to be set for the Tls handshake. The hostname will be set in the callback object that is given to the `SslContextProviderSupplier`, to be invoked with the `SslContext` when the client Ssl Provider instantiated by this supplier has the `SslContext` available. This value along with the `UpstreamTlsContext` available in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. From 724a3f91f78a1d94f643642439a4d74505820c84 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 13:13:21 +0530 Subject: [PATCH 49/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index b704bd1ab..3d1fc324b 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -96,14 +96,17 @@ matches the Subject Alternative Names specified in the server certificate agains [`match_subject_alt_names`][match_subject_alt_names] in `CertificateValidationContext`. If `auto_sni_san_validation` is set in the [UpstreamTlsContext][UTC], matching will be performed against the SNI that was used by the client, and this validation will replace -the [`match_subject_alt_names`][match_subject_alt_names] if set. This verification occurs -in the TrustManager created by the `CertificateProvider` using the cert store indicated by -`CertificateValidationContext` in `UpstreamTlsContext` which is either a managed cert store -or the system root cert store. - -#### (Java language specific) Caching for the SslContext -The `SslContextProviderSupplier` (named so because it supplies both client and server -SslContext providers) creates a provider for the client `SslContext` and today +the [`match_subject_alt_names`][match_subject_alt_names] if set. The value of the +`auto_sni_san_validation` field and the SNI used by the client will need to be propagated +to the certificate verifying mechanism that is used based on the settings in the +`CertificateProvider` when using `XdsChannelCredentials` for the transport. + +#### Language specific example +For example in Java the SAN SNI validation verification occurs in the TrustManager created by the `CertProviderClientSslContextProvider` using +the cert store indicated by `CertificateValidationContext` in `UpstreamTlsContext` which is either a managed cert store or the system root cert store. + +gRPC Java also has a Caching for the SslContext. The `SslContextProviderSupplier` (named so because it +supplies both client and server SslContext providers) creates a provider for the client `SslContext` and today maintains a cache of `UpstreamTlsContext` to the client `SslContext` provider instances. For the SNI requirement, the `TrustManager` in the `SslContext` needs to be aware of the SNI to validate the SAN against, so a different `TrustManager` instance needs From d165243ff17d268481f4f34629b487d4cd0760ef Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 13:18:48 +0530 Subject: [PATCH 50/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 3d1fc324b..43eacf263 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -119,9 +119,6 @@ SNI to validate the SANs against and set it in the `SslContext` it provides. [match_subject_alt_names]: https://github.com/envoyproxy/envoy/blob/b29d6543e7568a8a3e772c7909a1daa182acc670/api/envoy/extensions/transport_sockets/tls/v3/common.proto#L407 [UTC]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L29 -#### Behavior when SNI is not indicated in UpstreamTlsContext -When `UpstreamTlsContext` has neither of `SNI` nor `auto_sni_host` values set, the current behavior will continue, i.e. SNI will be set to the xds hostname from `GrpcRoute`. - #### Validation The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters, similar to Envoy. From c8cee5d381594628514a44d11dc1e9b9b88c28ed Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 13:40:35 +0530 Subject: [PATCH 51/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 43eacf263..3c915758d 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -51,9 +51,9 @@ Tls connections using the fields from [UpstreamTlsContext][UTC] in the CDS updat [A81-hostname]: A81-xds-authority-rewriting.md#xds-resource-validation 2. Server SAN validation against SNI used: If `auto_sni_san_validation` is true in the [UpstreamTlsContext][UTC] -gRPC client will perform validation for a DNS SAN matching the SNI value -sent. The normal matching when using `TlsCredentials` for the channel -allows other SAN types, but only the DNS type will be checked here. +gRPC client will perform matching for a SAN against the SNI used for the handshake. The normal matching when using +`TlsCredentials` for the channel only checks against DNS SANs in the certificate, but with `XdsChannelCredentials` +matching will be done using any of DNS / URI / IPA SAN types in the server certificate. ### Related Proposals: * [gRFC A29: xDS-Based Security for gRPC Clients and Servers][A29] @@ -76,6 +76,10 @@ cluster resource will also be set into the `CertificateProvider` by the xds_clus When the Tls handling code uses the certs and trust roots from the `CertificateProvider` to establish the connection, it will also now determine the SNI to set based on the parsed sni related fields available in the `CertificateProvider` and the hostname in the endpoint attributes. +The precedence order mentioned in the `Proposal1` section will be used to determine the SNI to use. For example, +if `UpstreamTlsContext.auto_host_sni` was set but there is no EDS hostname for the endpoint, but +`UpstreamTlsContext.sni` is set, then it would use the value of the `UpstreamTlsContext.sni` if set. +If no SNI value is determined, then it will no set SNI for the Tls handshake. [A81_xds_resource_validation]: A81-xds-authority-rewriting.md#xds-resource-validation @@ -100,6 +104,7 @@ the [`match_subject_alt_names`][match_subject_alt_names] if set. The value of th `auto_sni_san_validation` field and the SNI used by the client will need to be propagated to the certificate verifying mechanism that is used based on the settings in the `CertificateProvider` when using `XdsChannelCredentials` for the transport. +The SNI used by the client will be used for matching, regardless of how that SNI was determined. #### Language specific example For example in Java the SAN SNI validation verification occurs in the TrustManager created by the `CertProviderClientSslContextProvider` using From eac4fab627bb6a41a651b2fd33e8b28ad8cbbd0c Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 13:42:38 +0530 Subject: [PATCH 52/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 3c915758d..5dff2661c 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -66,7 +66,7 @@ matching will be done using any of DNS / URI / IPA SAN types in the server certi As mentioned in [A29 implementation details][A29_impl-details] the `UpstreamTlsContext` is either passed down to child policies via channel arguments or a similar mechanism, depending on the language. [A29 implementation details][A29_impl-details] also talks about a `CertificateProvider` object that represents -a plugin that provides the required certificates and keys to the gRPC application. When Tls handshake is +a plugin that provides the required certificates and keys to the gRPC implementation. When Tls handshake is initiated for a channel that is using `XdsCredentials`, this `CertificateProvider` object is used to provide the certs and trust roots for establishing the secure connection. During this handshake we need to set the SNI to use for the `ClientHello` frame of the handshake. To determine the SNI, we need both the From 970632175a46e612af7559a56225beb175e746ad Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 29 Aug 2025 13:44:19 +0530 Subject: [PATCH 53/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 5dff2661c..a6215a575 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -127,6 +127,10 @@ SNI to validate the SANs against and set it in the `SslContext` it provides. #### Validation The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters, similar to Envoy. -### Temporary environment variable protection +### Environment variable protections Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` env var. The env var guard will be removed once the feature passes interop tests. +When the SNI value to be used for the Tls handshake is not determined based on the described rules, no SNI will be +sent. Some language implementations are sending the xds channel authority today, and some customers may see +breaking behavior if no SNI is sent now. To mitigate this, an env var `GRPC_USE_CHANNEL_AUTHORITY_IF_NO_SNI_APPLICABLE` +will be provided to revert back to the old behavior of sending the xds channel authority when no SNI is determined. From 4253e7b23a874e8965f6c0a016d85bc94c9dc1ee Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 1 Sep 2025 17:35:39 +0530 Subject: [PATCH 54/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index a6215a575..ced18a4cf 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -76,20 +76,19 @@ cluster resource will also be set into the `CertificateProvider` by the xds_clus When the Tls handling code uses the certs and trust roots from the `CertificateProvider` to establish the connection, it will also now determine the SNI to set based on the parsed sni related fields available in the `CertificateProvider` and the hostname in the endpoint attributes. -The precedence order mentioned in the `Proposal1` section will be used to determine the SNI to use. For example, +The precedence order mentioned at the top of the [Proposal](#proposal) section will be used to determine the SNI to use. For example, if `UpstreamTlsContext.auto_host_sni` was set but there is no EDS hostname for the endpoint, but `UpstreamTlsContext.sni` is set, then it would use the value of the `UpstreamTlsContext.sni` if set. -If no SNI value is determined, then it will no set SNI for the Tls handshake. - -[A81_xds_resource_validation]: A81-xds-authority-rewriting.md#xds-resource-validation +If no SNI value is determined, then it will not set SNI for the Tls handshake. ##### Language specific example As an example, in Java, the ClusterImpl LB policy creates the `SslContextProviderSuppler` wrapping the `UpstreamTlsContext` and puts it in the subchannel wrapper when its child policy creates a subchannel. At the time of Tls protocol negotiation -for the subchannel, the hostname from the endpoint address attributes also should be passed to this provider supplier to determine the SNI to be set for -the Tls handshake. The hostname will be set in the callback object that is given to the `SslContextProviderSupplier`, to be invoked with the -`SslContext` when the client Ssl Provider instantiated by this supplier has the `SslContext` available. This value along with the -`UpstreamTlsContext` available in the `SslContextProviderSupplier` will be used to decide the SNI to be used for the handshake. +for the subchannel, the Tls handling code should use the hostname from the endpoint address attributes and the SNI related fields in `UpstreamTlsContext` +to determine the SNI to be used for the Tls handshake. This SNI will also be passed to the the `SslContextProviderSupplier`, in addition to the +callback to be invoked to provide the `SslContext` when it is available. The `ClientCertificateSslContextProvider` instantiated by the `SslContextProviderSupplier` +will be passed both the callback argument and the SNI value to use, that will be used in the `XdsX509TrustManager` it creates to perform the SAN - SNI +matching. The Tls protocol negotiating code will use the SNI value determined to use when creating the the SSL engine from the `SslContext` received via the callback. [A29_impl-details]: A29-xds-tls-security.md#implementation-details [UTC_SNI]: https://github.com/envoyproxy/envoy/blob/ee2bab9e40e7d7649cc88c5e1098c74e0c79501d/api/envoy/extensions/transport_sockets/tls/v3/tls.proto#L42 From 480f26f91b23ec88b0f52c9ee7fd8e1461d641d1 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Tue, 16 Sep 2025 15:30:43 +0530 Subject: [PATCH 55/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index ced18a4cf..01c1e8fd1 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -128,8 +128,8 @@ The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters ### Environment variable protections Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` -env var. The env var guard will be removed once the feature passes interop tests. -When the SNI value to be used for the Tls handshake is not determined based on the described rules, no SNI will be +env variable. The env variable guard will be present for several releases for the following reason. When the SNI value +to be used for the Tls handshake is not determined based on the described rules, no SNI will be sent. Some language implementations are sending the xds channel authority today, and some customers may see -breaking behavior if no SNI is sent now. To mitigate this, an env var `GRPC_USE_CHANNEL_AUTHORITY_IF_NO_SNI_APPLICABLE` -will be provided to revert back to the old behavior of sending the xds channel authority when no SNI is determined. +breaking behavior if no SNI is sent now. In that case they can revert back to the old behavior by turning off +the env variable. From 10f47ef71b2ae31afdd2d1d348db610f13a3dbfd Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 19 Sep 2025 16:16:10 +0530 Subject: [PATCH 56/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 01c1e8fd1..85e1d4472 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -84,7 +84,7 @@ If no SNI value is determined, then it will not set SNI for the Tls handshake. ##### Language specific example As an example, in Java, the ClusterImpl LB policy creates the `SslContextProviderSuppler` wrapping the `UpstreamTlsContext` and puts it in the subchannel wrapper when its child policy creates a subchannel. At the time of Tls protocol negotiation -for the subchannel, the Tls handling code should use the hostname from the endpoint address attributes and the SNI related fields in `UpstreamTlsContext` +for the subchannel, the Tls handling code should use the hostname from the endpoint attributes and the SNI related fields in `UpstreamTlsContext` to determine the SNI to be used for the Tls handshake. This SNI will also be passed to the the `SslContextProviderSupplier`, in addition to the callback to be invoked to provide the `SslContext` when it is available. The `ClientCertificateSslContextProvider` instantiated by the `SslContextProviderSupplier` will be passed both the callback argument and the SNI value to use, that will be used in the `XdsX509TrustManager` it creates to perform the SAN - SNI From 53bde84d81313a10c6540fb3927a155a8492b29a Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 19 Sep 2025 16:19:31 +0530 Subject: [PATCH 57/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 85e1d4472..0d04f506a 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -127,9 +127,8 @@ SNI to validate the SANs against and set it in the `SslContext` it provides. The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters, similar to Envoy. ### Environment variable protections -Setting SNI and performing the SAN validation against SNI will be guarded by the `GRPC_EXPERIMENTAL_XDS_SNI` -env variable. The env variable guard will be present for several releases for the following reason. When the SNI value -to be used for the Tls handshake is not determined based on the described rules, no SNI will be -sent. Some language implementations are sending the xds channel authority today, and some customers may see -breaking behavior if no SNI is sent now. In that case they can revert back to the old behavior by turning off -the env variable. +Setting SNI and performing the SAN validation against SNI will be guarded by the GRPC_EXPERIMENTAL_XDS_SNI env var. The env var guard will be removed once +the feature passes interop tests. When the SNI value to be used for the Tls handshake is not determined based on the described rules, no SNI will be sent. +Some language implementations are sending the xds channel authority today, and some customers may see breaking behavior if no SNI is sent now. To mitigate +this, an env var GRPC_USE_CHANNEL_AUTHORITY_IF_NO_SNI_APPLICABLE will be provided to revert back to the old behavior of sending the xds channel authority +when no SNI is determined. From 56f7732f05cffcd7c1206bcc9aca6d2a0b38c169 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Fri, 19 Sep 2025 16:21:30 +0530 Subject: [PATCH 58/58] Update A101-SNI-setting-and-SNI-SAN-validation.md --- A101-SNI-setting-and-SNI-SAN-validation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/A101-SNI-setting-and-SNI-SAN-validation.md b/A101-SNI-setting-and-SNI-SAN-validation.md index 0d04f506a..136c633b4 100644 --- a/A101-SNI-setting-and-SNI-SAN-validation.md +++ b/A101-SNI-setting-and-SNI-SAN-validation.md @@ -130,5 +130,5 @@ The Cds update will be NACKed if `UpstreamTlsContext.sni` exceeds 255 characters Setting SNI and performing the SAN validation against SNI will be guarded by the GRPC_EXPERIMENTAL_XDS_SNI env var. The env var guard will be removed once the feature passes interop tests. When the SNI value to be used for the Tls handshake is not determined based on the described rules, no SNI will be sent. Some language implementations are sending the xds channel authority today, and some customers may see breaking behavior if no SNI is sent now. To mitigate -this, an env var GRPC_USE_CHANNEL_AUTHORITY_IF_NO_SNI_APPLICABLE will be provided to revert back to the old behavior of sending the xds channel authority -when no SNI is determined. +this risk, an env var GRPC_USE_CHANNEL_AUTHORITY_IF_NO_SNI_APPLICABLE will be provided to revert back to the old behavior of sending the xds channel authority +when no SNI is determined. This value however will not be used for SAN verification.