From 3ca90ed8669fc467ca7627f0e690040971233d8b Mon Sep 17 00:00:00 2001
From: Anit Gandhi <agandhi@digitalocean.com>
Date: Tue, 27 Jun 2023 16:55:45 +0000
Subject: [PATCH] doc/go1.21: document changes in crypto/tls related to client
 authentication alerts

For #52113
For #58645

Change-Id: Id7dff2570132588da95fb4216a86faf34fa2cbdc
GitHub-Last-Rev: 94eabfe82f189b7a5fb7f1ee32ac3074aa58088f
GitHub-Pull-Request: golang/go#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 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/go1.21.html b/doc/go1.21.html
index 45b037a204a2b..a31956869e86b 100644
--- a/doc/go1.21.html
+++ b/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 -->