math/rand: make the security warning clearer and more prominent

It is still a common misconception that math/rand can be used for
security-sensitive work if seeded with crypto/rand
(lazyledger/lazyledger-core#270). It can not.

Change-Id: I8598c352d1750eabeada50be9976ab68cbb42cc0
Reviewed-on: https://go-review.googlesource.com/c/go/+/310350
Trust: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Katie Hockman <katie@golang.org>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>

diff --git a/src/math/rand/rand.go b/src/math/rand/rand.go
index d6422c914d87afe1bcd5158a6fb384024981b045..8179d9f4649a533a1175c19e3b8ed66a3564ebbf 100644 (file)
--- a/src/math/rand/rand.go
+++ b/src/math/rand/rand.go
@@ -2,7 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package rand implements pseudo-random number generators.
+// Package rand implements pseudo-random number generators unsuitable for
+// security-sensitive work.
 //
 // Random numbers are generated by a Source. Top-level functions, such as
 // Float64 and Int, use a default shared Source that produces a deterministic
@@ -14,8 +15,9 @@
 // Mathematical interval notation such as [0, n) is used throughout the
 // documentation for this package.
 //
-// For random numbers suitable for security-sensitive work, see the crypto/rand
-// package.
+// This package's outputs might be easily predictable regardless of how it's
+// seeded. For random numbers suitable for security-sensitive work, see the
+// crypto/rand package.
 package rand
 
 import "sync"