doc/go1.21: document changes in crypto/tls related to client authenti…

…cation alerts

For #52113
For #58645

Change-Id: Id7dff2570132588da95fb4216a86faf34fa2cbdc
GitHub-Last-Rev: 94eabfe
GitHub-Pull-Request: #60972
Reviewed-on: https://go-review.googlesource.com/c/go/+/505436
Run-TryBot: Roland Shoemaker <roland@golang.org>
Auto-Submit: Roland Shoemaker <roland@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>

doc/go1.21.html

@@ -585,6 +585,32 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
       The new <a href="/pkg/crypto/tls/#VersionName"><code>VersionName</code></a> function
       returns the name for a TLS version number.
     </p>
+
+    <p><!-- https://go.dev/issue/52113, CL 410496 -->
+      The TLS alert codes sent from the server for client authentication failures have
+      been improved. Prior to Go 1.21, these failures always resulted in a "bad certificate" alert.
+      Starting from Go 1.21, certain failures will result in more appropriate alert codes,
+      as defined by RFC 5246 and RFC 8446:
+      <ul>
+        <li>
+          For TLS 1.3 connections, if the server is configured to require client authentication using
+          <a href="/pkg/crypto/tls/#RequireAnyClientCert"></code>RequireAnyClientCert</code></a> or
+          <a href="/pkg/crypto/tls/#RequireAndVerifyClientCert"></code>RequireAndVerifyClientCert</code></a>,
+          and the client does not provide any certificate, the server will now return the "certificate required" alert.
+        </li>
+        <li>
+          If the client provides a certificate that is not signed by the set of trusted certificate authorities
+          configured on the server, the server will return the "unknown certificate authority" alert.
+        </li>
+        <li>
+          If the client provides a certificate that is either expired or not yet valid,
+          the server will return the "expired certificate" alert.
+        </li>
+        <li>
+          In all other scenarios related to client authentication failures, the server still returns "bad certificate".
+        </li>
+      </ul>
+    </p>
   </dd>
 </dl><!-- crypto/tls -->