Index: pkg/crypto/lib/src/hmac.dart |
diff --git a/pkg/crypto/lib/src/hmac.dart b/pkg/crypto/lib/src/hmac.dart |
index 2d07cff9a152502d1ecbd755c6c8fea4ab24a095..59c177109497d52a6319baa2a60f81765d628a0b 100644 |
--- a/pkg/crypto/lib/src/hmac.dart |
+++ b/pkg/crypto/lib/src/hmac.dart |
@@ -4,16 +4,32 @@ |
part of crypto; |
-class _HMAC implements HMAC { |
+/** |
+ * 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. |
+class HMAC { |
bool _isClosed = false; |
- _HMAC(Hash this._hash, List<int> this._key) : _message = []; |
+ /** |
+ * Create an [HMAC] object from a [Hash] and a key. |
+ */ |
+ HMAC(Hash this._hash, List<int> this._key) : _message = []; |
+ /** |
+ * Add a list of bytes to the message. |
+ */ |
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]. |
+ */ |
List<int> get digest { |
var blockSize = _hash.blockSize; |
@@ -58,11 +74,25 @@ class _HMAC implements HMAC { |
return _hash.close(); |
} |
+ /** |
+ * Perform the actual computation and extract the message digest |
+ * as a list of bytes. |
+ */ |
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. |
+ */ |
bool verify(List<int> digest) { |
var computedDigest = this.digest; |
if (digest.length != computedDigest.length) { |