doc/go1.17: add release notes for crypto packages

For #44513

Change-Id: I459b3a4f9936eaa2c09888177f91176140d04280
Reviewed-on: https://go-review.googlesource.com/c/go/+/325649
Trust: Filippo Valsorda <filippo@golang.org>
Trust: Katie Hockman <katie@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
Reviewed-by: Katie Hockman <katie@golang.org>

1 files changed, 108 insertions, 28 deletions

diff --git a/doc/go1.17.html b/doc/go1.17.html
index ba6b8baf19..c1b3b3cef4 100644
--- a/doc/go1.17.html
+++ b/doc/go1.17.html
@@ -338,30 +338,6 @@ Do not send CLs removing the interior tags from such phrases.
   TODO: complete the Core library section
 </p>
 
-<h3 id="crypto/tls"><a href="/pkg/crypto/tls">crypto/tls</a></h3>
-
-<p><!-- CL 295370 -->
-  <a href="/pkg/crypto/tls#Conn.HandshakeContext">(*Conn).HandshakeContext</a> was added to
-  allow the user to control cancellation of an in-progress TLS Handshake.
-  The context provided is propagated into the
-  <a href="/pkg/crypto/tls#ClientHelloInfo">ClientHelloInfo</a>
-  and <a href="/pkg/crypto/tls#CertificateRequestInfo">CertificateRequestInfo</a>
-  structs and accessible through the new
-  <a href="/pkg/crypto/tls#ClientHelloInfo.Context">(*ClientHelloInfo).Context</a>
-  and
-  <a href="/pkg/crypto/tls#CertificateRequestInfo.Context">
-      (*CertificateRequestInfo).Context
-  </a> methods respectively. Canceling the context after the handshake has finished
-  has no effect.
-</p>
-
-<p><!-- CL 289209 -->
-  When <a href="/pkg/crypto/tls#Config">Config.NextProtos</a> is set, servers now
-  enforce that there is an overlap between the configured protocols and the protocols
-  advertised by the client, if any. If there is no overlap the connection is closed
-  with the <code>no_application_protocol</code> alert, as required by RFC 7301.
-</p>
-
 <h3 id="runtime/cgo"><a href="/pkg/runtime/cgo">Cgo</a></h3>
 
 <p>
@@ -424,13 +400,117 @@ Do not send CLs removing the interior tags from such phrases.
   </dd>
 </dl><!-- compress/lzw -->
 
-<dl id="crypto/rsa"><dt><a href="/pkg/crypto/rsa/">crypto/rsa</a></dt>
+<dl id="crypto/ed25519"><dt><a href="/pkg/crypto/ed25519/">crypto/ed25519</a></dt>
+  <dd>
+    <p><!-- CL 276272 -->
+      The <code>crypto/ed25519</code> package has been rewritten, and all
+      operations are now approximately twice as fast on amd64 and arm64.
+      The observable behavior has not otherwise changed.
+    </p>
+  </dd>
+</dl><!-- crypto/ed25519 -->
+
+<dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
+  <dd>
+    <p><!-- CL 233939 -->
+      <a href="/pkg/crypto/elliptic#CurveParams"><code>CurveParams</code></a>
+      methods now automatically invoke faster and safer dedicated
+      implementations for known curves (P-224, P-256, and P-521) when
+      available. Note that this is a best-effort approach and applications
+      should avoid using the generic, not constant-time <code>CurveParams</code>
+      methods and instead use dedicated
+      <a href="/pkg/crypto/elliptic#Curve"><code>Curve</code></a> implementations
+      such as <a href="/pkg/crypto/elliptic#P256"><code>P256</code></a>.
+    </p>
+
+    <p><!-- CL 315271, CL 315274 -->
+      The <a href="/pkg/crypto/elliptic#P521"><code>P521</code></a> curve
+      implementation has been rewritten using code generated by the
+      <a href="https://github.com/mit-plv/fiat-crypto">fiat-crypto project</a>,
+      which is based on a formally-verified model of the arithmetic
+      operations. It is now constant-time and three times faster on amd64 and
+      arm64. The observable behavior has not otherwise changed.
+    </p>
+  </dd>
+</dl><!-- crypto/elliptic -->
+
+<dl id="crypto/rand"><dt><a href="/pkg/crypto/rand/">crypto/rand</a></dt>
+  <dd>
+    <p><!-- CL 302489, CL 299134, CL 269999 -->
+      The <code>crypto/rand</code> package now uses the <code>getentropy</code>
+      syscall on macOS and the <code>getrandom</code> syscall on Solaris,
+      Illumos, and DragonFlyBSD.
+    </p>
+  </dd>
+</dl><!-- crypto/rand -->
+
+<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
   <dd>
-    <p><!-- CL 302230 -->
-      TODO: <a href="https://golang.org/cl/302230">https://golang.org/cl/302230</a>: fix salt length calculation with PSSSaltLengthAuto
+    <p><!-- CL 295370 -->
+      The new <a href="/pkg/crypto/tls#Conn.HandshakeContext"><code>Conn.HandshakeContext</code></a>
+      method allows the user to control cancellation of an in-progress TLS
+      handshake. The provided context is accessible from various callbacks through the new
+      <a href="/pkg/crypto/tls#ClientHelloInfo.Context"><code>ClientHelloInfo.Context</code></a> and
+      <a href="/pkg/crypto/tls#CertificateRequestInfo.Context"><code>CertificateRequestInfo.Context</code></a>
+      methods. Canceling the context after the handshake has finished has no effect.
+    </p>
+
+    <p><!-- CL 289209 -->
+      When <a href="/pkg/crypto/tls#Config.NextProtos"><code>Config.NextProtos</code></a>
+      is set, servers now enforce that there is an overlap between the
+      configured protocols and the protocols advertised by the client, if any.
+      If there is no overlap the connection is closed with the
+      <code>no_application_protocol</code> alert, as required by RFC 7301.
+    </p>
+
+    <p><!-- CL 314609 -->
+      Cipher suite ordering is now handled entirely by the
+      <code>crypto/tls</code> package. Currently, cipher suites are sorted based
+      on their security, performance, and hardware support taking into account
+      both the local and peer's hardware. The order of the
+      <a href="/pkg/crypto/tls#Config.CipherSuites"><code>Config.CipherSuites</code></a>
+      field is now ignored, as well as the
+      <a href="/pkg/crypto/tls#Config.PreferServerCipherSuites"><code>Config.PreferServerCipherSuites</code></a>
+      field. Note that <code>Config.CipherSuites</code> still allows
+      applications to choose what TLS 1.0–1.2 cipher suites to enable.
+    </p>
+
+    <p>
+      The 3DES cipher suites have been moved to
+      <a href="/pkg/crypto/tls#InsecureCipherSuites"><code>InsecureCipherSuites</code></a>
+      due to <a href="https://sweet32.info/">fundamental block size-related
+      weakness</a>. They are still enabled by default but only as a last resort,
+      thanks to the cipher suite ordering change above.
+    </p>
+  </dd>
+</dl><!-- crypto/tls -->
+
+<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
+  <dd>
+    <p><!-- CL 224157 -->
+      <a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
+      now returns an error if the provided private key doesn't match the
+      parent's public key, if any. The resulting certificate would have failed
+      to verify.
+    </p>
+
+    <p><!-- CL 315209 -->
+      The temporary <code>GODEBUG=x509ignoreCN=0</code> flag has been removed.
+    </p>
+
+    <p><!-- CL 274234 -->
+      <a href="/pkg/crypto/x509/#ParseCertificate"><code>ParseCertificate</code></a>
+      has been rewritten, and now consumes ~70% fewer resources. The observable
+      behavior has not otherwise changed, except for error messages.
+    </p>
+
+    <p><!-- CL 321190 -->
+      On BSD systems, <code>/etc/ssl/certs</code> is now searched for trusted
+      roots. This adds support for the new system trusted certificate store in
+      FreeBSD 12.2+.
     </p>
   </dd>
-</dl><!-- crypto/rsa -->
+</dl><!-- crypto/x509 -->
 
 <dl id="database/sql"><dt><a href="/pkg/database/sql/">database/sql</a></dt>
   <dd>