math/big: correct documentation for ProbablyPrime.

As akalin points out in the bug, the comment previously claimed that the
probability that the input is prime given that the function returned
true is 1 - ¼ⁿ. But that's wrong: the correct statement is that the
probability of the function returning false given a composite input is
1 - ¼ⁿ.

This is not nearly as helpful, but at least it's truthful. A number of
other (correct) expressions are suggested on the bug, but I think that
the simplier one is preferable.

This change also notes that the function is not suitable for
adversarial inputs since it's deterministic.

Fixes #12274.

Change-Id: I6a0871d103b126ee5a5a922a8c6993055cb7b1ed
Reviewed-on: https://go-review.googlesource.com/14052
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/math/big/int.go b/src/math/big/int.go
index ac5c1f02244de4c4f7eb0fa0fec6ac774dac61a9..16b7cd131bd753a0d47e48eb832058285b10b631 100644 (file)
--- a/src/math/big/int.go
+++ b/src/math/big/int.go
@@ -551,8 +551,11 @@ func (z *Int) binaryGCD(a, b *Int) *Int {
 }
 
 // ProbablyPrime performs n Miller-Rabin tests to check whether x is prime.
-// If it returns true, x is prime with probability 1 - 1/4^n.
-// If it returns false, x is not prime. n must be > 0.
+// If x is prime, it returns true.
+// If x is not prime, it returns false with probability at least 1 - ¼ⁿ.
+//
+// It is not suitable for judging primes that an adversary may have crafted
+// to fool this test.
 func (x *Int) ProbablyPrime(n int) bool {
        if n <= 0 {
                panic("non-positive n for ProbablyPrime")

diff --git a/src/math/big/nat.go b/src/math/big/nat.go
index 121daec8292c9436e2b8ad7353357b1ed45e3053..54f4011ca5919ff6b60b597180000fc84fa60891 100644 (file)
--- a/src/math/big/nat.go
+++ b/src/math/big/nat.go
@@ -1121,9 +1121,12 @@ func (z nat) expNNMontgomery(x, y, m nat) nat {
        return zz.norm()
 }
 
-// probablyPrime performs reps Miller-Rabin tests to check whether n is prime.
-// If it returns true, n is prime with probability 1 - 1/4^reps.
-// If it returns false, n is not prime.
+// probablyPrime performs n Miller-Rabin tests to check whether x is prime.
+// If x is prime, it returns true.
+// If x is not prime, it returns false with probability at least 1 - ¼ⁿ.
+//
+// It is not suitable for judging primes that an adversary may have crafted
+// to fool this test.
 func (n nat) probablyPrime(reps int) bool {
        if len(n) == 0 {
                return false