Update documentation comments.
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//1348983002 .
diff --git a/lib/crypto.dart b/lib/crypto.dart
index 29fd62a..e6ffa55 100644
--- a/lib/crypto.dart
+++ b/lib/crypto.dart
@@ -2,10 +2,6 @@
// 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.
-/**
- * Cryptographic algorithms, with support for hash functions such as
- * SHA-1, SHA-256, HMAC, and MD5.
- */
library crypto;
export 'src/base64.dart';
diff --git a/lib/src/base64.dart b/lib/src/base64.dart
index ad0d8bc..b3896b6 100644
--- a/lib/src/base64.dart
+++ b/lib/src/base64.dart
@@ -7,8 +7,15 @@
import 'dart:convert';
import 'dart:typed_data';
+/// An instance of the default implementation of [Base64Codec].
+///
+/// This provides convenient access to most common Base64 use-cases.
const Base64Codec BASE64 = const Base64Codec();
+/// A mapping from ASCII character codes to their corresponding Base64 values.
+///
+/// Characters with a value of -2 are invalid. Characters with a value of -1
+/// should be ignored. The padding character, "=", is represented as 0.
const List<int> _decodeTable = const [
-2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -1, -2, -2, -1, -2, -2,
-2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2,
@@ -28,47 +35,64 @@
-2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2, -2
];
+/// A String representing a mapping from numbers between 0 and 63, inclusive, to
+/// their corresponding encoded character.
+///
+/// This is the table for URL-safe encodings.
const String _encodeTableUrlSafe =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/// A String representing a mapping from numbers between 0 and 63, inclusive, to
+/// their corresponding encoded character.
+///
+/// This is the table for URL-unsafe encodings.
const String _encodeTable =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/// The line length for Base64 strings with line separators.
const int _LINE_LENGTH = 76;
+
+/// A carriage return.
const int _CR = 13; // '\r'
+
+/// A line feed.
const int _LF = 10; // '\n'
+
+/// The byte sequence representing non-URL-encoded padding.
const List<int> _PAD_BYTES = const [61]; // '='
+
+/// The byte sequence representing URL-encoded padding.
const List<int> _ENCODED_PAD_BYTES = const [37, 51, 68]; // '%3D'
+
+/// The string representing non-URL-encoded padding.
const String _PAD = "=";
+
+/// The string representing URL-encoded padding.
const String _ENCODED_PAD = "%3D";
+/// A codec that converts between binary data and [Base64][rfc]-encoded strings.
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
class Base64Codec extends Codec<List<int>, String> {
final bool _urlSafe;
final bool _addLineSeparator;
final bool _encodePaddingCharacter;
- /**
- * Instantiates a new [Base64Codec].
- *
- * The optional [urlSafe] argument specifies if [encoder] and [encode]
- * should generate a string, that is safe to use in an URL.
- *
- * If [urlSafe] is `true` (and not overriden at the method invocation)
- * the [encoder] and [encode] use '-' instead of '+' and '_' instead of '/'.
- *
- * The default value of [urlSafe] is `false`.
- *
- * The optional [addLineSeparator] argument specifies if the [encoder] and
- * [encode] should add line separators.
- *
- * If `addLineSeparator` is `true` [encode] adds an
- * optional line separator (CR + LF) for each 76 char output.
- *
- * The default value of [addLineSeparator] if `false`.
- *
- * If [encodePaddingCharacter] is `true` `encode` converts `=` to `%3D`.
- * The default value of [encodePaddingCharacter] is `false`.
- */
+ /// Creates a new [Base64Codec].
+ ///
+ /// The default [BASE64] codec will be good enough for most cases. A new codec
+ /// only needs to be instantiated when you want to do multiple conversions
+ /// with the same configuration.
+ ///
+ /// If [urlSafe] is `true`, a URL-safe alphabet will be used when encoding.
+ /// Specifically, the characters `-` and `_` will be used instead of `+` and
+ /// `/`.
+ ///
+ /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+ /// every 76 characters when encoding.
+ ///
+ /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+ /// written as `%3D` when encoding.
const Base64Codec(
{bool urlSafe: false,
bool addLineSeparator: false,
@@ -79,6 +103,20 @@
String get name => "base64";
+ /// Encodes [bytes] into a Base64 string.
+ ///
+ /// If [urlSafe] is `true`, a URL-safe alphabet will be used when encoding.
+ /// Specifically, the characters `-` and `_` will be used instead of `+` and
+ /// `/`.
+ ///
+ /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+ /// every 76 characters when encoding.
+ ///
+ /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+ /// written as `%3D` when encoding.
+ ///
+ /// Any flags passed to this method take precedence over the flags passed to
+ /// the codec itself.
String encode(List<int> bytes,
{bool urlSafe, bool addLineSeparator, bool encodePaddingCharacter}) {
if (urlSafe == null) urlSafe = _urlSafe;
@@ -100,38 +138,36 @@
Base64Decoder get decoder => new Base64Decoder();
}
-/**
- * This class encodes byte strings (lists of unsigned
- * 8-bit integers) to strings according to Base64.
- */
+/// An encoder that converts sequences of bytes to strings using [Base64][rfc].
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
class Base64Encoder extends Converter<List<int>, String> {
+ /// Whether this encoder generates URL-safe strings.
final bool _urlSafe;
+
+ /// Whether this encoder adds line breaks to the output.
final bool _addLineSeparator;
+
+ /// Whether this encoder URL-encodes trailing padding characters.
final bool _encodePaddingCharacter;
+
+ /// The sequence of bytes to use as a padding character.
final List<int> _pad;
- /**
- * Instantiates a new [Base64Encoder].
- *
- * The optional [urlSafe] argument specifies if [convert]
- * should generate a string, that is safe to use in an URL.
- *
- * If it is `true` the [convert] use
- * '-' instead of '+' and '_' instead of '/'.
- *
- * The default value of [urlSafe] is `false`.
- *
- * The optional [addLineSeparator] argument specifies if [convert]
- * should add line separators.
- *
- * If it is `true` [convert] adds an optional line separator(CR + LF)
- * for each 76 char output.
- *
- * The default value of [addLineSeparator] if `false`.
- *
- * If [encodePaddingCharacter] is `true` `encode` converts `=` to `%3D`.
- * The default value of [encodePaddingCharacter] is `false`.
- */
+ /// Creates a new [Base64Encoder].
+ ///
+ /// The default [BASE64.encoder] will be good enough for most cases. A new
+ /// codec only needs to be instantiated when you want to do multiple
+ /// conversions with the same configuration.
+ ///
+ /// If [urlSafe] is `true`, a URL-safe alphabet will be used. Specifically,
+ /// the characters `-` and `_` will be used instead of `+` and `/`.
+ ///
+ /// If [addLineSeparator] is `true`, `\r\n` line separators will be added
+ /// every 76 characters.
+ ///
+ /// If [encodePaddingCharacter] is `true`, the padding character `=` will be
+ /// written as `%3D`.
const Base64Encoder(
{bool urlSafe: false,
bool addLineSeparator: false,
@@ -141,12 +177,10 @@
_encodePaddingCharacter = encodePaddingCharacter,
_pad = encodePaddingCharacter == true ? _ENCODED_PAD_BYTES : _PAD_BYTES;
- /**
- * Converts [bytes] to its Base64 representation as a string.
- *
- * if [start] and [end] are provided, only the sublist
- * `bytes.sublist(start, end)` is converted.
- */
+ /// Converts [bytes] to Base64.
+ ///
+ /// If [start] and [end] are provided, only the sublist `bytes.sublist(start,
+ /// end)` is converted.
String convert(List<int> bytes, [int start = 0, int end]) {
int bytes_length = bytes.length;
RangeError.checkValidRange(start, end, bytes_length);
@@ -224,10 +258,21 @@
}
}
+/// A [ChunkedConversionSink] for encoding chunks of data to Base64.
class _Base64EncoderSink extends ChunkedConversionSink<List<int>> {
+ /// The encoder used to encode each chunk.
final Base64Encoder _encoder;
+
+ /// The underlying sink to which to emit the encoded strings.
final ChunkedConversionSink<String> _outSink;
+
+ /// The buffer of as-yet-unconverted bytes.
+ ///
+ /// This is used to ensure that we don't generate interstitial padding
+ /// characters.
final List<int> _buffer = new List<int>();
+
+ /// The length of [_buffer]; that is, the number of unconverted bytes.
int _bufferCount = 0;
_Base64EncoderSink(this._outSink, urlSafe, addLineSeparator)
@@ -260,14 +305,10 @@
}
}
-/**
- * This class decodes strings to lists of bytes(lists of
- * unsigned 8-bit integers) according to Base64.
- */
+/// An encoder that converts [Base64][rfc] strings to sequences of bytes.
+///
+/// [rfc]: https://tools.ietf.org/html/rfc4648
class Base64Decoder extends Converter<String, List<int>> {
- /**
- * Instantiates a new [Base64Decoder]
- */
const Base64Decoder();
List<int> convert(String input) {
@@ -357,9 +398,18 @@
}
}
+/// A [ChunkedConversionSink] for decoding chunks of Base64 strings to data.
class _Base64DecoderSink extends ChunkedConversionSink<String> {
+ /// The encoder used to decode each chunk.
final Base64Decoder _decoder = new Base64Decoder();
+
+ /// The underlying sink to which to emit the decoded strings.
final ChunkedConversionSink<List<int>> _outSink;
+
+ /// The as-yet-unconverted text.
+ ///
+ /// This is used to handle a chunk stopping partway in the middle of a
+ /// URL-encoded `=` character.
String _unconverted = "";
_Base64DecoderSink(this._outSink);
diff --git a/lib/src/crypto_utils.dart b/lib/src/crypto_utils.dart
index 99613ef..821fd2b 100644
--- a/lib/src/crypto_utils.dart
+++ b/lib/src/crypto_utils.dart
@@ -6,14 +6,10 @@
import 'base64.dart';
-/**
- * Utility methods for working with message digests.
- */
+/// Utility methods for working with message digests.
abstract class CryptoUtils {
- /**
- * Convert a list of bytes (for example a message digest) into a hex
- * string.
- */
+ /// Convert a list of bytes (for example a message digest) into a hexadecimal
+ /// string.
static String bytesToHex(List<int> bytes) {
var result = new StringBuffer();
for (var part in bytes) {
@@ -22,37 +18,32 @@
return result.toString();
}
- /**
- * Converts a list of bytes into a Base 64 encoded string.
- *
- * The list can be any list of integers in the range 0..255,
- * for example a message digest.
- *
- * If [addLineSeparator] is true, the resulting string will be
- * broken into lines of 76 characters, separated by "\r\n".
- *
- * If [urlSafe] is true, the result is URL and filename safe.
- *
- * Based on [RFC 4648](http://tools.ietf.org/html/rfc4648)
- *
- */
+ /// 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.
+ ///
+ /// 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.
static String bytesToBase64(List<int> bytes,
{bool urlSafe: false, bool addLineSeparator: false}) {
return BASE64.encode(bytes,
urlSafe: urlSafe, addLineSeparator: addLineSeparator);
}
- /**
- * Converts a Base 64 encoded String into list of bytes.
- *
- * Decoder ignores "\r\n" sequences from input.
- *
- * Accepts both URL safe and unsafe Base 64 encoded strings.
- *
- * Throws a FormatException exception if input contains invalid characters.
- *
- * Based on [RFC 4648](http://tools.ietf.org/html/rfc4648)
- */
+ /// 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.
+ ///
+ /// Throws a [FormatException] if [input] contains invalid characters.
static List<int> base64StringToBytes(String input) {
return BASE64.decode(input);
}
diff --git a/lib/src/hash.dart b/lib/src/hash.dart
index 03d4b1c..bb228fa 100644
--- a/lib/src/hash.dart
+++ b/lib/src/hash.dart
@@ -4,42 +4,30 @@
library crypto.hash;
-/**
- * Interface for cryptographic hash functions.
- *
- * The [add] method is used to add data to the hash. The [close] method
- * is used to extract the message digest.
- *
- * Once the [close] method has been called no more data can be added using the
- * [add] method. If [add] is called after the first call to [close] a
- * HashException is thrown.
- *
- * If multiple instances of a given Hash is needed the [newInstance]
- * method can provide a new instance.
- */
+/// An interface for cryptographic hash functions.
+///
+/// The [add] method adds data to the hash. The [close] method extracts the
+/// message digest.
+///
+/// If multiple instances of a given Hash is needed, the [newInstance] method
+/// can provide a new instance.
// TODO(floitsch): make Hash implement Sink, EventSink or similar.
abstract class Hash {
- /**
- * Add a list of bytes to the hash computation.
- */
+ /// Add a list of bytes to the hash computation.
+ ///
+ /// If [this] has already been closed, throws a [StateError].
void add(List<int> data);
- /**
- * Finish the hash computation and extract the message digest as
- * a list of bytes.
- */
+ /// Finish the hash computation and extract the message digest as a list of
+ /// bytes.
List<int> close();
- /**
- * Returns a new instance of this hash function.
- */
+ /// Returns a new instance of this hash function.
Hash newInstance();
- /**
- * Internal block size of the hash in bytes.
- *
- * This is exposed for use by the HMAC class which needs to know the
- * block size for the [Hash] it is using.
- */
+ /// The internal block size of the hash in bytes.
+ ///
+ /// This is exposed for use by the [HMAC] class, which needs to know the block
+ /// size for the [Hash] it uses.
int get blockSize;
}
diff --git a/lib/src/hash_base.dart b/lib/src/hash_base.dart
index 796fd14..b77b26d 100644
--- a/lib/src/hash_base.dart
+++ b/lib/src/hash_base.dart
@@ -10,18 +10,44 @@
import 'hash.dart';
import 'utils.dart';
-// Base class encapsulating common behavior for cryptographic hash
-// functions.
+/// A base class for [Hash] implementations.
+///
+/// Subclasses should override [updateHash], and define it to update [h] with
+/// the results of the hash function.
abstract class HashBase implements Hash {
+ /// The size (in 32-bit words) of the chunks of input data that the hash
+ /// function consumes at once.
final int _chunkSizeInWords;
+
+ /// The size (in 32-bit words) of the digest that the hash function emits.
final int _digestSizeInWords;
+
+ /// Whether the hash function operates on big-endian words.
final bool _bigEndianWords;
+
+ /// The words in the current chunk.
final Uint32List _currentChunk;
+
+ /// The words in the current digest.
+ ///
+ /// The size of this buffer is given by the `digestSizeInWords` constructor
+ /// parameter.
final Uint32List h;
+
+ /// The length of the input data so far, in bytes.
int _lengthInBytes = 0;
+
+ /// Data that has yet to be processed by the hash function.
List<int> _pendingData;
+
+ /// Whether [close] has been called.
bool _digestCalled = false;
+ /// Creates a new hash.
+ ///
+ /// [chunkSizeInWords] represents the size of the input chunks processed by
+ /// the algorithm. [digestSizeInWords] represents the size of the algorithm's
+ /// output digest. Both are in terms of 32-bit words.
HashBase(
int chunkSizeInWords, int digestSizeInWords, bool this._bigEndianWords)
: _pendingData = [],
@@ -30,7 +56,6 @@
_chunkSizeInWords = chunkSizeInWords,
_digestSizeInWords = digestSizeInWords;
- // Update the hasher with more data.
void add(List<int> data) {
if (_digestCalled) {
throw new StateError(
@@ -41,7 +66,6 @@
_iterate();
}
- // Finish the hash computation and return the digest string.
List<int> close() {
if (_digestCalled) {
return _resultAsBytes();
@@ -53,15 +77,19 @@
return _resultAsBytes();
}
- // Returns the block size of the hash in bytes.
int get blockSize {
return _chunkSizeInWords * BYTES_PER_WORD;
}
- // One round of the hash computation.
+ /// Runs a single iteration of the hash computation, updating [h] with the
+ /// result.
+ ///
+ /// [m] is the current chunk, whose size is given by the `chunkSizeInWords`
+ /// parameter passed to the constructor.
void updateHash(Uint32List m);
- // Compute the final result as a list of bytes from the hash words.
+ /// Computes the final result of the hash as a list of bytes from the hash
+ /// words.
List<int> _resultAsBytes() {
var result = [];
for (var i = 0; i < h.length; i++) {
@@ -70,7 +98,9 @@
return result;
}
- // Converts a list of bytes to a chunk of 32-bit words.
+ /// Converts a list of bytes to a chunk of 32-bit words.
+ ///
+ /// Stores the result in [_currentChunk].
void _bytesToChunk(List<int> data, int dataIndex) {
assert((data.length - dataIndex) >= (_chunkSizeInWords * BYTES_PER_WORD));
@@ -88,7 +118,7 @@
}
}
- // Convert a 32-bit word to four bytes.
+ /// Converts a 32-bit word to four bytes.
List<int> _wordToBytes(int word) {
List bytes = new List<int>(BYTES_PER_WORD);
bytes[0] = (word >> (_bigEndianWords ? 24 : 0)) & MASK_8;
@@ -98,8 +128,8 @@
return bytes;
}
- // Iterate through data updating the hash computation for each
- // chunk.
+ /// Iterates through [_pendingData], updating the hash computation for each
+ /// chunk.
void _iterate() {
var len = _pendingData.length;
var chunkSizeInBytes = _chunkSizeInWords * BYTES_PER_WORD;
@@ -113,13 +143,15 @@
}
}
- // Finalize the data. Add a 1 bit to the end of the message. Expand with
- // 0 bits and add the length of the message.
+ /// Finalizes [_pendingData].
+ ///
+ /// This adds a 1 bit to the end of the message, and expands it with 0 bits to
+ /// pad it out.
void _finalizeData() {
_pendingData.add(0x80);
var contentsLength = _lengthInBytes + 9;
var chunkSizeInBytes = _chunkSizeInWords * BYTES_PER_WORD;
- var finalizedLength = roundUp(contentsLength, chunkSizeInBytes);
+ var finalizedLength = _roundUp(contentsLength, chunkSizeInBytes);
var zeroPadding = finalizedLength - contentsLength;
for (var i = 0; i < zeroPadding; i++) {
_pendingData.add(0);
@@ -138,4 +170,7 @@
_pendingData.addAll(_wordToBytes((lengthInBits >> 32) & MASK_32));
}
}
+
+ /// Rounds [val] to the nearest multiple of [n].
+ int _roundUp(val, n) => (val + n - 1) & -n;
}
diff --git a/lib/src/hmac.dart b/lib/src/hmac.dart
index 2e9e0ef..668f40f 100644
--- a/lib/src/hmac.dart
+++ b/lib/src/hmac.dart
@@ -6,35 +6,48 @@
import 'hash.dart';
-/**
- * Hash-based Message Authentication Code support.
- *
- * The [add] method is used to add data to the message. The [digest] and
- * [close] methods are used to extract the message authentication code.
- */
-// TODO(floitsch): make Hash implement Sink, EventSink or similar.
+/// An implementation of [keyed-hash method authentication codes][rfc].
+///
+/// [rfc]: https://tools.ietf.org/html/rfc2104
+///
+/// HMAC allows messages to be cryptographically authenticated using any
+/// iterated cryptographic hash function.
+///
+/// The message's data is added using [add]. Once it's been fully added, the
+/// [digest] and [close] methods can be used to extract the message
+/// authentication digest.
+///
+/// If an expected authentication digest is available, the [verify] method may
+/// also be used to ensure that the message actually corresponds to that digest.
+// TODO(floitsch): make HMAC implement Sink, EventSink or similar.
class HMAC {
+ /// The bytes from the message so far.
final List<int> _message;
+
+ /// The hash function used to compute the authentication digest.
Hash _hash;
+
+ /// The secret key shared by the sender and the receiver.
List<int> _key;
+
+ /// Whether this is closed.
bool _isClosed = false;
- /**
- * Create an [HMAC] object from a [Hash] and a key.
- */
+ /// 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 this._hash, List<int> this._key) : _message = [];
- /**
- * Add a list of bytes to the message.
- */
+ /// Adds a list of bytes to the message.
+ ///
+ /// If [this] has already been closed, throws a [StateError].
void add(List<int> data) {
if (_isClosed) throw new StateError("HMAC is closed");
_message.addAll(data);
}
- /**
- * Extract the message digest as a list of bytes without closing [this].
- */
+ /// Returns the digest of the message so far, as a list of bytes.
List<int> get digest {
var blockSize = _hash.blockSize;
@@ -79,25 +92,22 @@
return _hash.close();
}
- /**
- * Perform the actual computation and extract the message digest
- * as a list of bytes.
- */
+ /// Closes [this] and returns the digest of the message as a list of bytes.
+ ///
+ /// Once closed, [add] may no longer be called.
List<int> close() {
_isClosed = true;
return digest;
}
- /**
- * Verify that the HMAC computed for the data so far matches the
- * given message digest.
- *
- * This method should be used instead of memcmp-style comparisons
- * to avoid leaking information via timing.
- *
- * Throws an exception if the given digest does not have the same
- * size as the digest computed by this HMAC instance.
- */
+ /// 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].
bool verify(List<int> digest) {
var computedDigest = this.digest;
if (digest.length != computedDigest.length) {
diff --git a/lib/src/md5.dart b/lib/src/md5.dart
index 077b218..e1caf88 100644
--- a/lib/src/md5.dart
+++ b/lib/src/md5.dart
@@ -10,18 +10,22 @@
import 'hash_base.dart';
import 'utils.dart';
-/**
- * MD5 hash function implementation.
- *
- * WARNING: MD5 has known collisions and should only be used when
- * required for backwards compatibility.
- */
+/// An implementation of the [MD5][rfc] hash function.
+///
+/// [rfc]: https://tools.ietf.org/html/rfc1321
+///
+/// **Warning**: MD5 has known collisions and should only be used when required
+/// for backwards compatibility.
abstract class MD5 implements Hash {
factory MD5() = _MD5;
MD5 newInstance();
}
+/// The concrete implementation of [MD5].
+///
+/// This is separate so that it can extend [HashBase] without leaking additional
+/// public memebers.
class _MD5 extends HashBase implements MD5 {
_MD5() : super(16, 4, false) {
h[0] = 0x67452301;
@@ -30,11 +34,12 @@
h[3] = 0x10325476;
}
- // Returns a new instance of this Hash.
MD5 newInstance() {
return new _MD5();
}
+ /// Data from a non-linear mathematical function that functions as
+ /// reproducible noise.
static const _k = const [
0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a,
0xa8304613, 0xfd469501, 0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be,
@@ -49,6 +54,7 @@
0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391
];
+ /// Per-round shift amounts.
static const _r = const [
07, 12, 17, 22, 07, 12, 17, 22, 07, 12, 17, 22, 07, 12, 17, 22, 05, 09, 14,
20, 05, 09, 14, 20, 05, 09, 14, 20, 05, 09, 14, 20, 04, 11, 16, 23, 04, 11,
@@ -56,8 +62,6 @@
10, 15, 21, 06, 10, 15, 21
];
- // Compute one iteration of the MD5 algorithm with a chunk of
- // 16 32-bit pieces.
void updateHash(Uint32List m) {
assert(m.length == 16);
diff --git a/lib/src/sha1.dart b/lib/src/sha1.dart
index d059226..7041a6f 100644
--- a/lib/src/sha1.dart
+++ b/lib/src/sha1.dart
@@ -10,19 +10,26 @@
import 'hash_base.dart';
import 'utils.dart';
-/**
- * SHA1 hash function implementation.
- */
+/// An implementation of the [SHA-1][rfc] hash function.
+///
+/// [rfc]: http://tools.ietf.org/html/rfc3174
abstract class SHA1 implements Hash {
factory SHA1() = _SHA1;
SHA1 newInstance();
}
+/// The concrete implementation of [SHA1].
+///
+/// This is separate so that it can extend [HashBase] without leaking additional
+/// public memebers.
class _SHA1 extends HashBase implements SHA1 {
+ /// The sixteen words from the original chunk, extended to 80 words.
+ ///
+ /// This is an instance variable to avoid re-allocating, but its data isn't
+ /// used across invocations of [updateHash].
final Uint32List _w;
- // Construct a SHA1 hasher object.
_SHA1()
: _w = new Uint32List(80),
super(16, 5, true) {
@@ -33,13 +40,10 @@
h[4] = 0xC3D2E1F0;
}
- // Returns a new instance of this Hash.
SHA1 newInstance() {
return new _SHA1();
}
- // Compute one iteration of the SHA1 algorithm with a chunk of
- // 16 32-bit pieces.
void updateHash(Uint32List m) {
assert(m.length == 16);
diff --git a/lib/src/sha256.dart b/lib/src/sha256.dart
index 158f3f9..f66976d 100644
--- a/lib/src/sha256.dart
+++ b/lib/src/sha256.dart
@@ -10,19 +10,26 @@
import 'hash_base.dart';
import 'utils.dart';
-/**
- * SHA256 hash function implementation.
- */
+/// An implementation of the [SHA-256][rfc] hash function.
+///
+/// [rfc]: http://tools.ietf.org/html/rfc6234
abstract class SHA256 implements Hash {
factory SHA256() = _SHA256;
SHA256 newInstance();
}
+/// The concrete implementation of [SHA256].
+///
+/// This is separate so that it can extend [HashBase] without leaking additional
+/// public memebers.
class _SHA256 extends HashBase implements SHA256 {
+ /// The sixteen words from the original chunk, extended to 64 words.
+ ///
+ /// This is an instance variable to avoid re-allocating, but its data isn't
+ /// used across invocations of [updateHash].
final Uint32List _w;
- // Construct a SHA256 hasher object.
_SHA256()
: _w = new Uint32List(64),
super(16, 8, true) {
@@ -38,13 +45,11 @@
h[7] = 0x5be0cd19;
}
- // Returns a new instance of this Hash.
SHA256 newInstance() {
return new _SHA256();
}
- // Table of round constants. First 32 bits of the fractional
- // parts of the cube roots of the first 64 prime numbers.
+ /// Data from a non-linear function that functions as reproducible noise.
static const List<int> _K = const [
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b,
0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01,
@@ -61,7 +66,9 @@
0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
];
- // Helper functions as defined in http://tools.ietf.org/html/rfc6234
+ // The following helper functions are taken directly from
+ // http://tools.ietf.org/html/rfc6234.
+
_rotr32(n, x) => (x >> n) | ((x << (32 - n)) & MASK_32);
_ch(x, y, z) => (x & y) ^ ((~x & MASK_32) & z);
_maj(x, y, z) => (x & y) ^ (x & z) ^ (y & z);
@@ -70,8 +77,6 @@
_ssig0(x) => _rotr32(7, x) ^ _rotr32(18, x) ^ (x >> 3);
_ssig1(x) => _rotr32(17, x) ^ _rotr32(19, x) ^ (x >> 10);
- // Compute one iteration of the SHA256 algorithm with a chunk of
- // 16 32-bit pieces.
void updateHash(Uint32List M) {
assert(M.length == 16);
diff --git a/lib/src/utils.dart b/lib/src/utils.dart
index 3f8a5c9..f2f265d 100644
--- a/lib/src/utils.dart
+++ b/lib/src/utils.dart
@@ -4,20 +4,23 @@
library crypto.utils;
-// Constants.
+/// A bitmask that limits an integer to 8 bits.
const MASK_8 = 0xff;
+
+/// A bitmask that limits an integer to 32 bits.
const MASK_32 = 0xffffffff;
+
+/// The number of bits in a byte.
const BITS_PER_BYTE = 8;
+
+/// The number of bytes in a 32-bit word.
const BYTES_PER_WORD = 4;
-// Helper methods.
+/// Adds [x] and [y] with 32-bit overflow semantics.
int add32(x, y) => (x + y) & MASK_32;
-int roundUp(val, n) => (val + n - 1) & -n;
-
-// Helper functions used by more than one hasher.
-
-// Rotate left limiting to unsigned 32-bit values.
+/// Bitwise rotates [val] to the left by [shift], obeying 32-bit overflow
+/// semantics.
int rotl32(int val, int shift) {
var mod_shift = shift & 31;
return ((val << mod_shift) & MASK_32) |
