doc/go1.19: expand crypto release notes

Not included are the following changes that were backported to Go 1.18
minor releases.

bb1f441618 crypto/rand: properly handle large Read on windows
35998c0109 crypto/x509: only disable SHA-1 verification for certificates
0fca8a8f25 crypto/x509: fix Certificate.Verify crash
fe4de36198 crypto/tls: randomly generate ticket_age_add
37065847d8 crypto/elliptic: tolerate zero-padded scalars in generic P-256
9a53b472b5 crypto/x509: properly handle issuerUniqueID and subjectUniqueID

The following are the benchmarks to back up the 3x speedup claim in the
crypto/elliptic notes.

name                    old time/op    new time/op    delta
pkg:crypto/elliptic goos:darwin goarch:arm64
ScalarBaseMult/P256-8   18.3µs ± 0%    18.2µs ± 0%      -0.56%  (p=0.000 n=10+10)
ScalarBaseMult/P224-8    233µs ± 0%      74µs ± 0%     -68.09%  (p=0.000 n=9+10)
ScalarBaseMult/P384-8    805µs ± 0%     236µs ± 0%     -70.73%  (p=0.000 n=8+10)
ScalarBaseMult/P521-8   2.50ms ± 0%    0.68ms ± 0%     -72.63%  (p=0.000 n=10+8)
ScalarMult/P256-8       68.4µs ± 0%    68.6µs ± 0%      +0.26%  (p=0.000 n=10+10)
ScalarMult/P224-8        234µs ± 0%     231µs ± 0%      -1.18%  (p=0.000 n=10+8)
ScalarMult/P384-8        805µs ± 0%     805µs ± 0%        ~     (p=0.211 n=9+10)
ScalarMult/P521-8       2.50ms ± 0%    2.49ms ± 0%      -0.69%  (p=0.000 n=10+10)
pkg:crypto/ecdsa goos:darwin goarch:arm64
Sign/P256-8             31.9µs ± 1%    31.7µs ± 0%      -0.64%  (p=0.001 n=10+10)
Sign/P224-8              264µs ± 0%     106µs ± 0%     -60.09%  (p=0.000 n=10+10)
Sign/P384-8              884µs ± 0%     313µs ± 0%     -64.53%  (p=0.000 n=9+10)
Sign/P521-8             2.64ms ± 0%    0.84ms ± 0%     -68.13%  (p=0.000 n=9+9)
Verify/P256-8           91.6µs ± 0%    91.7µs ± 0%        ~     (p=0.052 n=10+10)
Verify/P224-8            486µs ± 0%     300µs ± 0%     -38.15%  (p=0.000 n=9+9)
Verify/P384-8           1.66ms ± 0%    1.01ms ± 0%     -39.12%  (p=0.000 n=10+9)
Verify/P521-8           5.12ms ± 1%    3.06ms ± 0%     -40.27%  (p=0.000 n=10+10)
GenerateKey/P256-8      19.6µs ± 0%    19.4µs ± 0%      -0.79%  (p=0.000 n=10+10)
GenerateKey/P224-8       235µs ± 0%      76µs ± 1%     -67.45%  (p=0.000 n=8+10)
GenerateKey/P384-8       807µs ± 0%     239µs ± 0%     -70.43%  (p=0.000 n=9+10)
GenerateKey/P521-8      2.49ms ± 0%    0.69ms ± 0%     -72.36%  (p=0.000 n=9+10)

Change-Id: I7fb2db3aea4aac785a48d45fff7a32909f3b578c
Reviewed-on: https://go-review.googlesource.com/c/go/+/419355
Reviewed-by: Roland Shoemaker <roland@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

1 files changed, 74 insertions, 18 deletions

diff --git a/doc/go1.19.html b/doc/go1.19.html
index 41ffe8ebfd..3ce2233ab0 100644
--- a/doc/go1.19.html
+++ b/doc/go1.19.html
@@ -322,16 +322,58 @@ as well as support for rendering them to HTML, Markdown, and text.
   </dd>
 </dl><!-- archive/zip -->
 
+<dl id="crypto/elliptic"><dt><a href="/pkg/crypto/elliptic/">crypto/elliptic</a></dt>
+  <dd>
+    <p><!-- CL 382995 -->
+      Operating on invalid curve points (those for which the
+      <code>IsOnCurve</code> method returns false, and which are never returned
+      by <code>Unmarshal</code> or by a <code>Curve</code> method operating on a
+      valid point) has always been undefined behavior and can lead to key
+      recovery attacks. If an invalid point is supplied to
+      <a href="/pkg/crypto/elliptic/#Marshal"><code>Marshal</code></a>,
+      <a href="/pkg/crypto/elliptic/#MarshalCompressed"><code>MarshalCompressed</code></a>,
+      <a href="/pkg/crypto/elliptic/#Curve.Add"><code>Add</code></a>,
+      <a href="/pkg/crypto/elliptic/#Curve.Double"><code>Double</code></a>, or
+      <a href="/pkg/crypto/elliptic/#Curve.ScalarMult"><code>ScalarMult</code></a>,
+      they will now panic.
+    </p>
+
+    <p><!-- golang.org/issue/52182 -->
+      <code>ScalarBaseMult</code> operations on the <code>P224</code>,
+      <code>P384</code>, and <code>P521</code> curves are now up to three
+      times faster, leading to similar speedups in some ECDSA operations. The
+      generic (not platform optimized) <code>P256</code> implementation was
+      replaced with one derived from a formally verified model; this might
+      lead to significant slowdowns on 32-bit platforms.
+    </p>
+  </dd>
+</dl><!-- crypto/elliptic -->
+
 <dl id="crypto/rand"><dt><a href="/pkg/crypto/rand/">crypto/rand</a></dt>
   <dd>
     <p><!-- CL 370894 --><!-- CL 390038 -->
       <a href="/pkg/crypto/rand/#Read"><code>Read</code></a> no longer buffers
-      random data obtained from the operating system between calls.
+      random data obtained from the operating system between calls. Applications
+      that perform many small reads at high frequency might choose to wrap
+      <a href="/pkg/crypto/rand/#Reader"><code>Reader</code></a> in a
+      <a href="/pkg/bufio/#Reader"><code>bufio.Reader</code></a> for performance
+      reasons, taking care to use
+      <a href="/pkg/io/#ReadFull"><code>io.ReadFull</code></a>
+      to ensure no partial reads occur.
     </p>
 
     <p><!-- CL 375215 -->
       On Plan 9, <code>Read</code> has been reimplemented, replacing the ANSI
-      X9.31 algorithm with fast key erasure.
+      X9.31 algorithm with a fast key erasure generator.
+    </p>
+
+    <p><!-- CL 391554 --><!-- CL 387554 -->
+      The <a href="/pkg/crypto/rand/#Prime"><code>Prime</code></a>
+      implementation was simplified. This will lead to different outputs for the
+      same random stream compared to the previous implementation. The internals
+      of <code>Prime</code> are not stable, should not be relied upon not to
+      change, and the output is now intentionally non-deterministic with respect
+      to the input stream.
     </p>
   </dd>
 </dl><!-- crypto/rand -->
@@ -364,6 +406,19 @@ as well as support for rendering them to HTML, Markdown, and text.
       <code>CreateCertificate</code> no longer accepts negative serial numbers.
     </p>
 
+    <p><!-- CL 399827 -->
+      <code>CreateCertificate</code> will not emit an empty SEQUENCE anymore
+      when the produced certificate has no extensions.
+    </p>
+
+    <p><!-- CL 396774 -->
+      Removal of the <code>x509sha1=1</code> <code>GODEBUG</code> option,
+      originally planned for Go 1.19, has been rescheduled to a future release.
+      Applications using it should work on migrating. Practical attacks against
+      SHA-1 have been demonstrated since 2017 and publicly trusted Certificate
+      Authorities have not issued SHA-1 certificates since 2015.
+    </p>
+
     <p><!-- CL 383215 -->
       <a href="/pkg/crypto/x509/#ParseCertificate"><code>ParseCertificate</code></a>
       and <a href="/pkg/crypto/x509/#ParseCertificateRequest"><code>ParseCertificateRequest</code></a>
@@ -373,7 +428,7 @@ as well as support for rendering them to HTML, Markdown, and text.
     <p><!-- https://go.dev/issue/46057 --><!-- https://go.dev/issue/35044 --><!-- CL 398237 --><!-- CL 400175 --><!-- CL 388915 -->
       The new <a href="/pkg/crypto/x509/#CertPool.Clone"><code>CertPool.Clone</code></a>
       and <a href="/pkg/crypto/x509/#CertPool.Equal"><code>CertPool.Equal</code></a>
-      methods allow cloning a <code>CertPool</code> and checking the equality of two
+      methods allow cloning a <code>CertPool</code> and checking the equivalence of two
       <code>CertPool</code>s respectively.
     </p>
 
@@ -381,25 +436,26 @@ as well as support for rendering them to HTML, Markdown, and text.
       The new function <a href="/pkg/crypto/x509/#ParseRevocationList"><code>ParseRevocationList</code></a>
       provides a faster, safer to use CRL parser which returns a
       <a href="/pkg/crypto/x509/#RevocationList"><code>RevocationList</code></a>.
-      To support this addition, <code>RevocationList</code> adds new fields
+      Parsing a CRL also populates the new <code>RevocationList</code> fields
       <code>RawIssuer</code>, <code>Signature</code>,
-      <code>AuthorityKeyId</code>, and <code>Extensions</code>.
-
+      <code>AuthorityKeyId</code>, and <code>Extensions</code>, which are ignored by
+      <a href="/pkg/crypto/x509/#CreateRevocationList"><code>CreateRevocationList</code></a>.
+    </p><p>
       The new method <a href="/pkg/crypto/x509/#RevocationList.CheckSignatureFrom"><code>RevocationList.CheckSignatureFrom</code></a>
       checks that the signature on a CRL is a valid signature from a
       <a href="/pkg/crypto/x509/#Certificate"><code>Certificate</code></a>.
-
-      With the new CRL functionality, the existing functions
-      <a href="/pkg/crypto/x509/#ParseCRL"><code>ParseCRL</code></a> and
-      <a href="/pkg/crypto/x509/#ParseDERCRL"><code>ParseDERCRL</code></a> are deprecated.
-      Additionally the method <a href="/pkg/crypto/x509#Certificate.CheckCRLSignature"><code>Certificate.CheckCRLSignature</code></a>
-      is deprecated.
-    </p>
-
-    <p><!-- CL 389555 -->
-      When building paths, <a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>
-      now considers certificates to be equal when the subjects, public keys, and SANs
-      are all equal. Before, it required byte-for-byte equality.
+    </p><p>
+      The <a href="/pkg/crypto/x509/#ParseCRL"><code>ParseCRL</code></a> and
+      <a href="/pkg/crypto/x509/#ParseDERCRL"><code>ParseDERCRL</code></a> functions
+      are now deprecated in favor of <code>ParseRevocationList</code>.
+      The <a href="/pkg/crypto/x509#Certificate.CheckCRLSignature"><code>Certificate.CheckCRLSignature</code></a>
+      method is deprecated in favor of <code>RevocationList.CheckSignatureFrom</code>.
+    </p>
+
+    <p><!-- CL 389555, CL 401115, CL 403554 -->
+      The path builder of <a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>
+      was overhauled and should now produce better chains and/or be more efficient in complicated scenarios.
+      Name constraints are now also enforced on non-leaf certificates.
     </p>
   </dd>
 </dl><!-- crypto/x509 -->