Update deprecations.

This deprecates:

* Classes that used the wrong capitalization.
* Base64 APIs, which are now available in the core libraries.
* CryptoUtils, whose functionality is now available in the core
  libraries and the convert package.

It also updates the deprecation message in already-deprecated APIs to
correspond to only mention the version in which the APIs will be
removed. The alternative APIs are mentioned in doc comments instead.

[email protected]

Review URL: https://codereview.chromium.org//1826543003 .

CHANGELOG.md

@@ -6,6 +6,9 @@
   `Hash.startChunkedConversion`—should be used in preference to the old APIs,
   which are now deprecated.
 
+* `SHA1`, `SHA256`, and `HMAC` have been renamed to `Sha1`, `Sha256`, and
+  `Hmac`, respectively. The old names still work, but are deprecated.
+
 * Top-level `sha1`, `sha256`, and `md5` fields have been added to make it easier
   to use those hash algorithms without having to instantiate new instances.
 
@@ -17,8 +20,20 @@
   `Hash.convert` should be used for hashing single values, and
   `Hash.startChunkedConversion` should be used for hashing streamed values.
 
-* `new SHA1()`, `new SHA256()`, and `new MD5()` are deprecated. Use the
-  top-level `sha1`, `sha256`, and `md5` fields instead.
+* `SHA1` and `SHA256` are deprecated. Use the top-level `sha1` and `sha256`
+  fields instead.
+
+* While the `MD5` class is not deprecated, the `new MD5()` constructor is. Use
+  the top-level `md5` field instead.
+
+* `HMAC` is deprecated. Use `Hmac` instead.
+
+* `Base64Codec`, `Base64Encoder`, `Base64Decoder`, `Base64EncoderSink`,
+  `Base64DecoderSink`, and `BASE64` are deprecated. Use the Base64 APIs in
+  `dart:convert` instead.
+
+* `CryptoUtils` is deprecated. Use the Base64 APIs in `dart:convert` and the hex
+  APIs in the `convert` package instead.
 
 ## 0.9.1
 

lib/src/base64.dart

@@ -7,14 +7,16 @@ import 'dart:convert';
 import 'base64/decoder.dart';
 import 'base64/encoder.dart';
 
-/// An instance of the default implementation of [Base64Codec].
+/// This is deprecated.
 ///
-/// This provides convenient access to most common Base64 use-cases.
+/// Use the `BASE64` constant in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 const Base64Codec BASE64 = const Base64Codec();
 
-/// A codec that converts between binary data and [Base64][rfc]-encoded strings.
+/// This is deprecated.
 ///
-/// [rfc]: https://tools.ietf.org/html/rfc4648
+/// Use the `Base64Codec` class in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 class Base64Codec extends Codec<List<int>, String> {
   final bool _urlSafe;
   final bool _addLineSeparator;

lib/src/base64/decoder.dart

@@ -24,9 +24,10 @@ const _decodeTable = const [
   38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51
 ];
 
-/// An encoder that converts [Base64][rfc] strings to sequences of bytes.
+/// This is deprecated.
 ///
-/// [rfc]: https://tools.ietf.org/html/rfc4648
+/// Use the `Base64Decoder` class in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 class Base64Decoder extends Converter<String, List<int>> {
   const Base64Decoder();
 

lib/src/base64/decoder_sink.dart

@@ -6,7 +6,10 @@ import 'dart:convert';
 
 import 'decoder.dart';
 
-/// A [ChunkedConversionSink] for decoding chunks of Base64 strings to data.
+/// This is deprecated.
+///
+/// Use the `Base64Decoder` class in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 class Base64DecoderSink extends ChunkedConversionSink<String> {
   /// The encoder used to decode each chunk.
   final Base64Decoder _decoder = new Base64Decoder();

lib/src/base64/encoder.dart

@@ -25,9 +25,10 @@ const _encodeTable =
 /// The line length for Base64 strings with line separators.
 const _lineLength = 76;
 
-/// An encoder that converts sequences of bytes to strings using [Base64][rfc].
+/// This is deprecated.
 ///
-/// [rfc]: https://tools.ietf.org/html/rfc4648
+/// Use the `Base64Encoder` class in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 class Base64Encoder extends Converter<List<int>, String> {
   /// Whether this encoder generates URL-safe strings.
   final bool _urlSafe;

lib/src/base64/encoder_sink.dart

@@ -6,7 +6,10 @@ import 'dart:convert';
 
 import 'encoder.dart';
 
-/// A [ChunkedConversionSink] for encoding chunks of data to Base64.
+/// This is deprecated.
+///
+/// Use the `Base64Encoder` class in `dart:convert` instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
 class Base64EncoderSink extends ChunkedConversionSink<List<int>> {
   /// The encoder used to encode each chunk.
   final Base64Encoder _encoder;

lib/src/crypto_utils.dart

@@ -4,10 +4,12 @@
 
 import 'base64.dart';
 
-/// Utility methods for working with message digests.
+/// This class is deprecated.
+@Deprecated("Will be removed in crypto 1.0.0.")
 abstract class CryptoUtils {
-  /// Convert a list of bytes (for example a message digest) into a hexadecimal
-  /// string.
+  /// This is deprecated.
+  ///
+  /// Use `hex` from `package:convert` instead.
   static String bytesToHex(List<int> bytes) {
     var result = new StringBuffer();
     for (var part in bytes) {
@@ -16,30 +18,16 @@ abstract class CryptoUtils {
     return result.toString();
   }
 
-  /// Converts a list of bytes into a [Base64-encoded][rfc] string.
-  ///
-  /// [rfc]: https://tools.ietf.org/html/rfc4648
-  ///
-  /// The list can be any list of integers from 0 to 255 inclusive, for example
-  /// a message digest.
+  /// This is deprecated.
   ///
-  /// If [addLineSeparator] is true, the resulting string will  be
-  /// broken into lines of 76 characters, separated by "\r\n".
-  ///
-  /// If [urlSafe] is true, the resulting string will be URL- and filename-
-  /// safe.
+  /// Use `BASE64` from `dart:convert` instead.
   static String bytesToBase64(List<int> bytes,
           {bool urlSafe: false, bool addLineSeparator: false}) =>
       BASE64.encode(bytes,
           urlSafe: urlSafe, addLineSeparator: addLineSeparator);
 
-  /// Converts a [Base64-encoded][rfc] String into list of bytes.
-  ///
-  /// [rfc]: https://tools.ietf.org/html/rfc4648
-  ///
-  /// This ignores "\r\n" sequences in [input]. It accepts both URL-safe and
-  /// -unsafe Base 64 encoded strings.
+  /// This is deprecated.
   ///
-  /// Throws a [FormatException] if [input] contains invalid characters.
+  /// Use `BASE64` from `dart:convert` instead.
   static List<int> base64StringToBytes(String input) => BASE64.decode(input);
 }

lib/src/digest.dart

@@ -2,7 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'crypto_utils.dart';
+import 'package:convert/convert.dart';
 
 /// A message digest as computed by a [Hash] or [HMAC] function.
 class Digest {
@@ -29,5 +29,5 @@ class Digest {
   }
 
   /// The message digest as a string of hexadecimal digits.
-  String toString() => CryptoUtils.bytesToHex(bytes);
+  String toString() => hex.encode(bytes);
 }

lib/src/hash.dart

@@ -40,21 +40,22 @@ abstract class Hash extends Converter<List<int>, Digest> {
 
   ByteConversionSink startChunkedConversion(Sink<Digest> sink);
 
-  /// Returns a new instance of this hash function.
-  @Deprecated("Expires in 1.0.0. Use Hash.startChunkedConversion() instead.")
+  /// This is deprecated.
+  ///
+  /// Use [startChunkedConversion] instead.
+  @Deprecated("Will be removed in crypto 1.0.0.")
   Hash newInstance();
 
-  /// Add a list of bytes to the hash computation.
+  /// This is deprecated.
   ///
-  /// If [this] has already been closed, throws a [StateError].
-  @Deprecated("Expires in 1.0.0. Use Hash.convert() or "
-      "Hash.startChunkedConversion() instead.")
+  /// Use [convert] or [startChunkedConversion] instead.
+  @Deprecated("Will be removed in crypto 1.0.0.")
   void add(List<int> data) => _sink.add(data);
 
-  /// Finish the hash computation and extract the message digest as a list of
-  /// bytes.
-  @Deprecated("Expires in 1.0.0. Use Hash.convert() or "
-      "Hash.startChunkedConversion() instead.")
+  /// This is deprecated.
+  ///
+  /// Use [convert] or [startChunkedConversion] instead.
+  @Deprecated("Will be removed in crypto 1.0.0.")
   List<int> close() {
     _sink.close();
     return _innerSink.value.bytes;

lib/src/hmac.dart

@@ -17,28 +17,18 @@ import 'hash.dart';
 ///
 /// HMAC allows messages to be cryptographically authenticated using any
 /// iterated cryptographic hash function.
-class HMAC extends Converter<List<int>, Digest> {
+class Hmac extends Converter<List<int>, Digest> {
   /// The hash function used to compute the authentication digest.
   final Hash _hash;
 
   /// The secret key shared by the sender and the receiver.
   final Uint8List _key;
 
-  /// The bytes from the message so far.
-  final _message = new Uint8Buffer();
-
-  /// The sink for implementing the deprecated APIs that involved adding data
-  /// directly to the [HMAC] instance.
-  _HmacSink _sink;
-
-  /// The sink that [_sink] sends the [Digest] to once it finishes hashing.
-  DigestSink _innerSink;
-
   /// Create an [HMAC] object from a [Hash] and a binary key.
   ///
   /// The key should be a secret shared between the sender and receiver of the
   /// message.
-  HMAC(Hash hash, List<int> key)
+  Hmac(Hash hash, List<int> key)
       : _hash = hash,
         _key = new Uint8List(hash.blockSize) {
     // Hash the key if it's longer than the block size of the hash.
@@ -47,9 +37,6 @@ class HMAC extends Converter<List<int>, Digest> {
     // If [key] is shorter than the block size, the rest of [_key] will be
     // 0-padded.
     _key.setRange(0, key.length, key);
-
-    _innerSink = new DigestSink();
-    _sink = startChunkedConversion(_innerSink);
   }
 
   Digest convert(List<int> data) {
@@ -62,30 +49,44 @@ class HMAC extends Converter<List<int>, Digest> {
 
   ByteConversionSink startChunkedConversion(Sink<Digest> sink) =>
       new _HmacSink(sink, _hash, _key);
+}
+
+/// This is deprecated.
+///
+/// Use [Hmac] instead.
+@Deprecated("Will be removed in crypto 1.0.0.")
+class HMAC {
+  final Hmac _hmac;
+
+  /// The sink for implementing the deprecated APIs that involved adding data
+  /// directly to the [HMAC] instance.
+  _HmacSink _sink;
+
+  /// The sink that [_sink] sends the [Digest] to once it finishes hashing.
+  DigestSink _innerSink;
 
-  /// Adds a list of bytes to the message.
+  /// The bytes from the message so far.
+  final _message = new Uint8Buffer();
+
+  /// Create an [HMAC] object from a [Hash] and a binary key.
   ///
-  /// If [this] has already been closed, throws a [StateError].
-  @Deprecated("Expires in 1.0.0. Use HMAC.convert() or "
-      "HMAC.startChunkedConversion() instead.")
+  /// The key should be a secret shared between the sender and receiver of the
+  /// message.
+  HMAC(Hash hash, List<int> key) : _hmac = new Hmac(hash, key) {
+    _innerSink = new DigestSink();
+    _sink = _hmac.startChunkedConversion(_innerSink);
+  }
+
   void add(List<int> data) {
     _message.addAll(data);
     _sink.add(data);
   }
 
-  /// Closes [this] and returns the digest of the message as a list of bytes.
-  ///
-  /// Once closed, [add] may no longer be called.
-  @Deprecated("Expires in 1.0.0. Use HMAC.convert() or "
-      "HMAC.startChunkedConversion() instead.")
   List<int> close() {
     _sink.close();
     return _innerSink.value.bytes;
   }
 
-  /// Returns the digest of the message so far, as a list of bytes.
-  @Deprecated("Expires in 1.0.0. Use HMAC.convert() or "
-      "HMAC.startChunkedConversion() instead.")
   List<int> get digest {
     if (_sink._isClosed) return _innerSink.value.bytes;
 
@@ -97,27 +98,18 @@ class HMAC extends Converter<List<int>, Digest> {
     var bytes = _innerSink.value.bytes;
 
     _innerSink = new DigestSink();
-    _sink = _hash.startChunkedConversion(_innerSink);
+    _sink = _hmac._hash.startChunkedConversion(_innerSink);
     _sink.add(_message);
 
     return bytes;
   }
 
-  /// Returns whether the digest computed for the data so far matches the given
-  /// [digest].
-  ///
-  /// This method should be used instead of iterative comparisons to avoid
-  /// leaking information via timing.
-  ///
-  /// Throws an [ArgumentError] if the given digest does not have the same size
-  /// as the digest computed by [this].
-  @Deprecated("Expires in 1.0.0. Use Digest.==() instead.")
   bool verify(List<int> digest) {
     var computedDigest = this.digest;
     if (digest.length != computedDigest.length) {
       throw new ArgumentError(
           'Invalid digest size: ${digest.length} in HMAC.verify. '
-          'Expected: ${_hash.blockSize}.');
+          'Expected: ${_hmac._hash.blockSize}.');
     }
 
     var result = 0;

lib/src/md5.dart

@@ -32,7 +32,10 @@ final md5 = new MD5();
 class MD5 extends Hash {
   final int blockSize = 16 * bytesPerWord;
 
-  @Deprecated("Use the md5 field instead.")
+  /// This constructor is deprecated.
+  ///
+  /// Use [md5] instead.
+  @Deprecated("Will be removed in crypto 1.0.0.")
   MD5();
 
   MD5 newInstance() => new MD5();