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>

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.

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 @@ import (
 	"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 @@ func (e *G1) ScalarMult(a *G1, k *big.Int) *G1 {
 }
 
 // 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 @@ func (e *G2) ScalarMult(a *G2, k *big.Int) *G2 {
 }
 
 // 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)

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"

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 (

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 (

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

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 (

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]

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

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 (