A101: xDS-Based setting SNI and server certificate SAN validation

A98-SNI-setting-and-SNI-SAN-validation.md → 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)
@@ -38,23 +38,21 @@ 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.
+    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][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.
+
+   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?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 
-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:
@@ -64,21 +62,25 @@ 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
-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.
+### 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.
+
+##### 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
@@ -105,12 +107,15 @@ need to be enhanced to be <UpstreamTlsContext, String> 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
 
 #### 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`.
+
+#### 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`