all: deprecate broken and legacy packages
Fixes golang/go#30141
Change-Id: I76f8eae31cfd6d106440114685cc0d9abba374f8
Reviewed-on: https://go-review.googlesource.com/c/163537
Reviewed-by: Adam Langley <agl@golang.org>
diff --git a/blowfish/cipher.go b/blowfish/cipher.go
index 2641dad..213bf20 100644
--- a/blowfish/cipher.go
+++ b/blowfish/cipher.go
@@ -3,6 +3,14 @@
// license that can be found in the LICENSE file.
// Package blowfish implements Bruce Schneier's Blowfish encryption algorithm.
+//
+// Blowfish is a legacy cipher and its short block size makes it vulnerable to
+// birthday bound attacks (see https://sweet32.info). It should only be used
+// where compatibility with legacy systems, not security, is the goal.
+//
+// Deprecated: any new system should use AES (from crypto/aes, if necessary in
+// an AEAD mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from
+// golang.org/x/crypto/chacha20poly1305).
package blowfish // import "golang.org/x/crypto/blowfish"
// The code is a port of Bruce Schneier's C implementation.
diff --git a/bn256/bn256.go b/bn256/bn256.go
index ff27feb..b081c6a 100644
--- a/bn256/bn256.go
+++ b/bn256/bn256.go
@@ -15,9 +15,14 @@
// http://cryptojedi.org/papers/dclxvi-20100714.pdf. Its output is compatible
// with the implementation described in that paper.
//
-// (This package previously claimed to operate at a 128-bit security level.
+// This package previously claimed to operate at a 128-bit security level.
// However, recent improvements in attacks mean that is no longer true. See
-// https://moderncrypto.org/mail-archive/curves/2016/000740.html.)
+// https://moderncrypto.org/mail-archive/curves/2016/000740.html.
+//
+// Deprecated: due to its weakened security, new systems should not rely on this
+// elliptic curve. This package is frozen, and not implemented in constant time.
+// There is a more complete implementation at github.com/cloudflare/bn256, but
+// note that it suffers from the same security issues of the underlying curve.
package bn256 // import "golang.org/x/crypto/bn256"
import (
@@ -26,9 +31,6 @@
"math/big"
)
-// BUG(agl): this implementation is not constant time.
-// TODO(agl): keep GF(p²) elements in Mongomery form.
-
// G1 is an abstract cyclic group. The zero value is suitable for use as the
// output of an operation, but cannot be used as an input.
type G1 struct {
@@ -77,7 +79,8 @@
}
// Add sets e to a+b and then returns e.
-// BUG(agl): this function is not complete: a==b fails.
+//
+// Warning: this function is not complete, it fails for a equal to b.
func (e *G1) Add(a, b *G1) *G1 {
if e.p == nil {
e.p = newCurvePoint(nil)
@@ -198,7 +201,8 @@
}
// Add sets e to a+b and then returns e.
-// BUG(agl): this function is not complete: a==b fails.
+//
+// Warning: this function is not complete, it fails for a equal to b.
func (e *G2) Add(a, b *G2) *G2 {
if e.p == nil {
e.p = newTwistPoint(nil)
diff --git a/cast5/cast5.go b/cast5/cast5.go
index 0b4af37..ddcbeb6 100644
--- a/cast5/cast5.go
+++ b/cast5/cast5.go
@@ -2,8 +2,15 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package cast5 implements CAST5, as defined in RFC 2144. CAST5 is a common
-// OpenPGP cipher.
+// Package cast5 implements CAST5, as defined in RFC 2144.
+//
+// CAST5 is a legacy cipher and its short block size makes it vulnerable to
+// birthday bound attacks (see https://sweet32.info). It should only be used
+// where compatibility with legacy systems, not security, is the goal.
+//
+// Deprecated: any new system should use AES (from crypto/aes, if necessary in
+// an AEAD mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from
+// golang.org/x/crypto/chacha20poly1305).
package cast5 // import "golang.org/x/crypto/cast5"
import "errors"
diff --git a/md4/md4.go b/md4/md4.go
index 6d9ba9e..59d3480 100644
--- a/md4/md4.go
+++ b/md4/md4.go
@@ -3,6 +3,10 @@
// license that can be found in the LICENSE file.
// Package md4 implements the MD4 hash algorithm as defined in RFC 1320.
+//
+// Deprecated: MD4 is cryptographically broken and should should only be used
+// where compatibility with legacy systems, not security, is the goal. Instead,
+// use a secure hash like SHA-256 (from crypto/sha256).
package md4 // import "golang.org/x/crypto/md4"
import (
diff --git a/otr/otr.go b/otr/otr.go
index 1be103f..29121e9 100644
--- a/otr/otr.go
+++ b/otr/otr.go
@@ -4,6 +4,10 @@
// Package otr implements the Off The Record protocol as specified in
// http://www.cypherpunks.ca/otr/Protocol-v2-3.1.0.html
+//
+// The version of OTR implemented by this package has been deprecated
+// (https://bugs.otr.im/lib/libotr/issues/140). An implementation of OTRv3 is
+// available at https://github.com/coyim/otr3.
package otr // import "golang.org/x/crypto/otr"
import (
diff --git a/ripemd160/ripemd160.go b/ripemd160/ripemd160.go
index fd97ba1..cf3eeb1 100644
--- a/ripemd160/ripemd160.go
+++ b/ripemd160/ripemd160.go
@@ -3,6 +3,10 @@
// license that can be found in the LICENSE file.
// Package ripemd160 implements the RIPEMD-160 hash algorithm.
+//
+// Deprecated: RIPEMD-160 is a legacy hash and should not be used for new
+// applications. Also, this package does not and will not provide an optimized
+// implementation. Instead, use a modern hash like SHA-256 (from crypto/sha256).
package ripemd160 // import "golang.org/x/crypto/ripemd160"
// RIPEMD-160 is designed by Hans Dobbertin, Antoon Bosselaers, and Bart
diff --git a/tea/cipher.go b/tea/cipher.go
index ce223b2..c1ff90e 100644
--- a/tea/cipher.go
+++ b/tea/cipher.go
@@ -5,6 +5,14 @@
// Package tea implements the TEA algorithm, as defined in Needham and
// Wheeler's 1994 technical report, “TEA, a Tiny Encryption Algorithm”. See
// http://www.cix.co.uk/~klockstone/tea.pdf for details.
+//
+// TEA is a legacy cipher and its short block size makes it vulnerable to
+// birthday bound attacks (see https://sweet32.info). It should only be used
+// where compatibility with legacy systems, not security, is the goal.
+//
+// Deprecated: any new system should use AES (from crypto/aes, if necessary in
+// an AEAD mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from
+// golang.org/x/crypto/chacha20poly1305).
package tea
import (
diff --git a/twofish/twofish.go b/twofish/twofish.go
index 6db01fc..1197d75 100644
--- a/twofish/twofish.go
+++ b/twofish/twofish.go
@@ -3,6 +3,12 @@
// license that can be found in the LICENSE file.
// Package twofish implements Bruce Schneier's Twofish encryption algorithm.
+//
+// Deprecated: Twofish is a legacy cipher and should not be used for new
+// applications. Also, this package does not and will not provide an optimized
+// implementation. Instead, use AES (from crypto/aes, if necessary in an AEAD
+// mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from
+// golang.org/x/crypto/chacha20poly1305).
package twofish // import "golang.org/x/crypto/twofish"
// Twofish is defined in https://www.schneier.com/paper-twofish-paper.pdf [TWOFISH]
diff --git a/xtea/cipher.go b/xtea/cipher.go
index 1661cbe..a4c2fd0 100644
--- a/xtea/cipher.go
+++ b/xtea/cipher.go
@@ -4,6 +4,14 @@
// Package xtea implements XTEA encryption, as defined in Needham and Wheeler's
// 1997 technical report, "Tea extensions."
+//
+// XTEA is a legacy cipher and its short block size makes it vulnerable to
+// birthday bound attacks (see https://sweet32.info). It should only be used
+// where compatibility with legacy systems, not security, is the goal.
+//
+// Deprecated: any new system should use AES (from crypto/aes, if necessary in
+// an AEAD mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from
+// golang.org/x/crypto/chacha20poly1305).
package xtea // import "golang.org/x/crypto/xtea"
// For details, see http://www.cix.co.uk/~klockstone/xtea.pdf
diff --git a/xts/xts.go b/xts/xts.go
index 9654e1f..f08582b 100644
--- a/xts/xts.go
+++ b/xts/xts.go
@@ -15,10 +15,12 @@
// effectively create a unique key for each sector.
//
// XTS does not provide any authentication. An attacker can manipulate the
-// ciphertext and randomise a block (16 bytes) of the plaintext.
+// ciphertext and randomise a block (16 bytes) of the plaintext. This package
+// does not implement ciphertext-stealing so sectors must be a multiple of 16
+// bytes.
//
-// (Note: this package does not implement ciphertext-stealing so sectors must
-// be a multiple of 16 bytes.)
+// Note that XTS is usually not appropriate for any use besides disk encryption.
+// Most users should use an AEAD mode like GCM (from crypto/cipher.NewGCM) instead.
package xts // import "golang.org/x/crypto/xts"
import (
