From 8c9ba318361080ea198c7461b6db621022d0a88e Mon Sep 17 00:00:00 2001 From: Filippo Valsorda Date: Sun, 7 Sep 2025 15:18:22 +0200 Subject: all: freeze and deprecate more packages Fixes golang/go#65250 Change-Id: I6a6a6964a2c87e529be50dd67fec462483b07b75 Reviewed-on: https://go-review.googlesource.com/c/crypto/+/701535 Reviewed-by: Mark Freeman Auto-Submit: Filippo Valsorda Reviewed-by: Daniel McCarney LUCI-TryBot-Result: Go LUCI Reviewed-by: Michael Pratt --- curve25519/curve25519.go | 11 +++++++---- ed25519/ed25519.go | 11 +++++++---- nacl/auth/auth.go | 29 ++++++++++------------------- nacl/sign/sign.go | 21 ++++++++------------- otr/otr.go | 4 ++++ pkcs12/pkcs12.go | 14 +++++++++----- salsa20/salsa/hsalsa20.go | 4 ++++ ssh/test/doc.go | 2 ++ xts/xts.go | 4 ++++ 9 files changed, 55 insertions(+), 45 deletions(-) diff --git a/curve25519/curve25519.go b/curve25519/curve25519.go index 8ff087d..048faef 100644 --- a/curve25519/curve25519.go +++ b/curve25519/curve25519.go @@ -3,11 +3,14 @@ // license that can be found in the LICENSE file. // Package curve25519 provides an implementation of the X25519 function, which -// performs scalar multiplication on the elliptic curve known as Curve25519. -// See RFC 7748. +// performs scalar multiplication on the elliptic curve known as Curve25519 +// according to [RFC 7748]. // -// This package is a wrapper for the X25519 implementation -// in the crypto/ecdh package. +// The curve25519 package is a wrapper for the X25519 implementation in the +// crypto/ecdh package. It is [frozen] and is not accepting new features. +// +// [RFC 7748]: https://datatracker.ietf.org/doc/html/rfc7748 +// [frozen]: https://go.dev/wiki/Frozen package curve25519 import "crypto/ecdh" diff --git a/ed25519/ed25519.go b/ed25519/ed25519.go index 59b3a95..df453dc 100644 --- a/ed25519/ed25519.go +++ b/ed25519/ed25519.go @@ -2,16 +2,19 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -// Package ed25519 implements the Ed25519 signature algorithm. See -// https://ed25519.cr.yp.to/. +// Package ed25519 implements the Ed25519 signature algorithm. // // These functions are also compatible with the “Ed25519” function defined in -// RFC 8032. However, unlike RFC 8032's formulation, this package's private key +// [RFC 8032]. However, unlike RFC 8032's formulation, this package's private key // representation includes a public key suffix to make multiple signing // operations with the same key more efficient. This package refers to the RFC // 8032 private key as the “seed”. // -// This package is a wrapper around the standard library crypto/ed25519 package. +// The ed25519 package is a wrapper for the Ed25519 implementation in the +// crypto/ed25519 package. It is [frozen] and is not accepting new features. +// +// [RFC 8032]: https://datatracker.ietf.org/doc/html/rfc8032 +// [frozen]: https://go.dev/wiki/Frozen package ed25519 import ( diff --git a/nacl/auth/auth.go b/nacl/auth/auth.go index 1d588d5..1360938 100644 --- a/nacl/auth/auth.go +++ b/nacl/auth/auth.go @@ -2,25 +2,16 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -/* -Package auth authenticates a message using a secret key. - -The Sum function, viewed as a function of the message for a uniform random -key, is designed to meet the standard notion of unforgeability. This means -that an attacker cannot find authenticators for any messages not authenticated -by the sender, even if the attacker has adaptively influenced the messages -authenticated by the sender. For a formal definition see, e.g., Section 2.4 -of Bellare, Kilian, and Rogaway, "The security of the cipher block chaining -message authentication code," Journal of Computer and System Sciences 61 (2000), -362–399; http://www-cse.ucsd.edu/~mihir/papers/cbc.html. - -auth does not make any promises regarding "strong" unforgeability; perhaps -one valid authenticator can be converted into another valid authenticator for -the same message. NaCl also does not make any promises regarding "truncated -unforgeability." - -This package is interoperable with NaCl: https://nacl.cr.yp.to/auth.html. -*/ +// Package auth authenticates a message using a secret key. +// +// This package is interoperable with [NaCl]. +// +// The auth package is essentially a wrapper for HMAC-SHA-512 (implemented by +// crypto/hmac and crypto/sha512), truncated to 32 bytes. It is [frozen] and is +// not accepting new features. +// +// [NaCl]: https://nacl.cr.yp.to/auth.html +// [frozen]: https://go.dev/wiki/Frozen package auth import ( diff --git a/nacl/sign/sign.go b/nacl/sign/sign.go index 109c08b..1cf2c4b 100644 --- a/nacl/sign/sign.go +++ b/nacl/sign/sign.go @@ -4,20 +4,15 @@ // Package sign signs small messages using public-key cryptography. // -// Sign uses Ed25519 to sign messages. The length of messages is not hidden. -// Messages should be small because: -// 1. The whole message needs to be held in memory to be processed. -// 2. Using large messages pressures implementations on small machines to process -// plaintext without verifying the signature. This is very dangerous, and this API -// discourages it, but a protocol that uses excessive message sizes might present -// some implementations with no other choice. -// 3. Performance may be improved by working with messages that fit into data caches. -// Thus large amounts of data should be chunked so that each message is small. +// This package is interoperable with [libsodium], as well as [TweetNaCl]. // -// This package is not interoperable with the current release of NaCl -// (https://nacl.cr.yp.to/sign.html), which does not support Ed25519 yet. However, -// it is compatible with the NaCl fork libsodium (https://www.libsodium.org), as well -// as TweetNaCl (https://tweetnacl.cr.yp.to/). +// The sign package is essentially a wrapper for the Ed25519 signature +// algorithm (implemented by crypto/ed25519). It is [frozen] and is not accepting +// new features. +// +// [libsodium]: https://libsodium.gitbook.io/doc/public-key_cryptography/public-key_signatures +// [TweetNaCl]: https://tweetnacl.cr.yp.to/ +// [frozen]: https://go.dev/wiki/Frozen package sign import ( diff --git a/otr/otr.go b/otr/otr.go index 6210c1a..a36f7ca 100644 --- a/otr/otr.go +++ b/otr/otr.go @@ -8,6 +8,10 @@ // 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. +// +// The otr package is [frozen] and is not accepting new features. +// +// [frozen]: https://go.dev/wiki/Frozen package otr import ( diff --git a/pkcs12/pkcs12.go b/pkcs12/pkcs12.go index 3a89bdb..374d9fa 100644 --- a/pkcs12/pkcs12.go +++ b/pkcs12/pkcs12.go @@ -4,12 +4,16 @@ // Package pkcs12 implements some of PKCS#12. // -// This implementation is distilled from https://tools.ietf.org/html/rfc7292 -// and referenced documents. It is intended for decoding P12/PFX-stored -// certificates and keys for use with the crypto/tls package. +// This implementation is distilled from [RFC 7292] and referenced documents. +// It is intended for decoding P12/PFX-stored certificates and keys for use +// with the crypto/tls package. // -// This package is frozen. If it's missing functionality you need, consider -// an alternative like software.sslmate.com/src/go-pkcs12. +// The pkcs12 package is [frozen] and is not accepting new features. +// If it's missing functionality you need, consider an alternative like +// software.sslmate.com/src/go-pkcs12. +// +// [RFC 7292]: https://datatracker.ietf.org/doc/html/rfc7292 +// [frozen]: https://go.dev/wiki/Frozen package pkcs12 import ( diff --git a/salsa20/salsa/hsalsa20.go b/salsa20/salsa/hsalsa20.go index 3685b34..75df774 100644 --- a/salsa20/salsa/hsalsa20.go +++ b/salsa20/salsa/hsalsa20.go @@ -3,6 +3,10 @@ // license that can be found in the LICENSE file. // Package salsa provides low-level access to functions in the Salsa family. +// +// Deprecated: this package exposes unsafe low-level operations. New applications +// should consider using the AEAD construction in golang.org/x/crypto/chacha20poly1305 +// instead. Existing users should migrate to golang.org/x/crypto/salsa20. package salsa import "math/bits" diff --git a/ssh/test/doc.go b/ssh/test/doc.go index 444b299..865781c 100644 --- a/ssh/test/doc.go +++ b/ssh/test/doc.go @@ -4,4 +4,6 @@ // Package test contains integration tests for the // golang.org/x/crypto/ssh package. +// +// Deprecated: this package is for internal use only. package test diff --git a/xts/xts.go b/xts/xts.go index d64f536..6a73020 100644 --- a/xts/xts.go +++ b/xts/xts.go @@ -21,6 +21,10 @@ // // 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. +// +// The xts package is [frozen] and is not accepting new features. +// +// [frozen]: https://go.dev/wiki/Frozen package xts import ( -- cgit v1.3