gep: refine ClientCertificateRef description for backend TLS

Signed-off-by: Norwin Schnyder <[email protected]>

Author: snorwin

geps/gep-3155/index.md

@@ -63,19 +63,34 @@ type GatewayTLSConfig struct {
     ...
 }
 type GatewayBackendTLS struct {
-  // ClientCertificateRef is a reference to an object that contains a Client
-  // Certificate and the associated private key.
+  // ClientCertificateRef references an object that contains a client certificate 
+  // and its associated private key. It can reference standard Kubernetes resources,
+  // i.e., Secret, or implementation-specific custom resources.
   //
-  // References to a resource in different namespace are invalid UNLESS there
-  // is a ReferenceGrant in the target namespace that allows the certificate
-  // to be attached. If a ReferenceGrant does not allow this reference, the
-  // "ResolvedRefs" condition MUST be set to False for this listener with the
-  // "RefNotPermitted" reason.
+  // This setting can be overridden on the service level by use of BackendTLSPolicy.
   //
-  // ClientCertificateRef can reference to standard Kubernetes resources, i.e.
-  // Secret, or implementation-specific custom resources.
+  // A ClientCertificateRef is considered invalid if:
   //
-  // This setting can be overridden on the service level by use of BackendTLSPolicy.
+  // * It refers to a resource that cannot be resolved (e.g., the referenced resource
+  //   does not exist) or is misconfigured (e.g., a Secret does not contain the keys
+  //   named `tls.crt` and `tls.key`). In this case, the `ResolvedRefs` condition 
+  //   on the Gateway MUST be set to False with the Reason `InvalidClientCertificateRef`
+  //   and the Message of the Condition MUST indicate why the reference is invalid.
+  //
+  // * It refers to a resource in another namespace UNLESS there is a ReferenceGrant
+  //   in the target namespace that allows the certificate to be attached.
+  //   If a ReferenceGrant does not allow this reference, the `ResolvedRefs` condition 
+  //   on the Gateway MUST be set to False with the Reason `RefNotPermitted`.
+  //
+  // Implementations MAY choose to perform further validation of the certificate
+  // content (e.g., checking expiry or enforcing specific formats). In such cases,
+  // an implementation-specific Reason and Message MUST be set.
+  //
+  // Support: Core - Reference to a Kubernetes TLS Secret (with the type `kubernetes.io/tls`).
+  // Support: Implementation-specific - Other resource kinds or Secrets with a
+  // different type (e.g., `Opaque`).
+  // +optional
+  // <gateway:experimental>
   ClientCertificateRef SecretObjectReference `json:"clientCertificateRef,omitempty"`
 }
 ```