Skip to content

Repository files navigation

hashlib

package version dart support likes pub points codecov Test Ask DeepWiki

A pure-Dart library of secure hash functions, checksums, MACs, key-derivation functions, OTP generators, and secure random — a broad, fast, dependency-light toolbox that runs everywhere Dart does.

hashlib is the middle layer of a three-package family:

convertlibhashlibcipherlib

It builds on convertlib for hex, Base32/Base64, and UTF-8 conversion, and that is its only runtime dependency.

Highlights

  • Runs on every platform: pure Dart with no native code or FFI, so the same library works everywhere Dart does — the VM, Flutter (Android, iOS, Windows, macOS, Linux), and the web (dart2js and dart2wasm).
  • Batteries included: over a dozen hash families (MD, SHA-1, SHA-2, SHA-3, SHAKE, Keccak, BLAKE2, RIPEMD, SM3, xxHash), checksums (CRC, Adler-32), MACs (HMAC, Poly1305), password KDFs (Argon2, scrypt, bcrypt, PBKDF2), TOTP/HOTP, and RNG/UUID generators.
  • One-shot or streaming: hash a String or byte buffer in a single call, or feed data incrementally through a reusable sink for large or chunked input.
  • Password-grade KDFs: Argon2id, scrypt, bcrypt, and PBKDF2 with named security presets that make the cost/latency trade-off explicit.
  • Fast: consistently outruns crypto, PointyCastle, and hash, see the benchmarks below.
  • Codecs and secure random built in: companion codecs and random libraries ship in the same package.

Install

dependencies:
  hashlib: ^2.4.2

or run dart pub add hashlib. A single import exposes every algorithm:

import 'package:hashlib/hashlib.dart';

Two companion libraries pair well with it — codecs for hex/Base/UTF-8 conversion (re-exported from convertlib) and random for secure random bytes, numbers, and UUIDs:

import 'package:hashlib/codecs.dart'; // toHex, fromHex, toBase64, toUtf8
import 'package:hashlib/random.dart'; // randomBytes, uuid, HashlibRandom

Full API reference: hashlib library.

Which tool do I need?

A hash turns any input — text, a file, bytes — into a short, fixed-size "fingerprint". Different jobs need different tools. Here is the plain-English map:

Your goal Reach for Examples
Fingerprint data, detect changes, build a cache key a cryptographic hash sha256, blake2b256
Store a user password safely a password KDF (slow on purpose) argon2id, bcrypt
Prove a message came from someone who knows a secret key a MAC sha256.hmac, poly1305
Quickly catch accidental corruption (not attackers) a checksum crc32, adler32
Generate 2FA / one-time login codes an OTP generator TOTP, HOTP
Generate unguessable tokens, IDs, or salts secure random randomBytes, uuid

Three rules of thumb if you are new to this:

  • Never store a password as a plain hash — not even sha256. Use a KDF like argon2id; it is deliberately slow, which makes guessing passwords expensive.
  • Checksums are not security. crc32, adler32, and the xxHash family are fast but trivial to forge. Use them against accidents, never against an attacker.
  • Unsure which cryptographic hash? sha256 is the safe universal default; blake2b256 is faster. Avoid md5 and sha1 for anything security-related.

Quickstart

import 'package:hashlib/hashlib.dart';

void main() {
  // A hex fingerprint of some text — that's the whole idea.
  print(sha256.string('Happy Hashing!').hex());
}

Every algorithm follows the same shape: call it on a String, a List<int>, or a stream, then read the result as hex, Base64, raw bytes, or a BigInt. The Usage section below shows one short recipe per task.

Supported algorithms

Block hash algorithms

Algorithm Available methods Source
MD2 md2, md2sum RFC-1319
MD4 md4, md4sum RFC-1320
MD5 md5, md5sum RFC-1321
SHA-1 sha1, sha1sum RFC-3174
SHA-2 sha224, sha256, sha384, sha512, sha512t224, sha512t256 RFC-6234
SHA-3 sha3_224, sha3_256, sha3_384, sha3_512 FIPS-202
SHAKE-128 Shake128, shake128, shake128_128, shake128_256 FIPS-202
SHAKE-256 Shake256, shake256, shake256_256, shake256_512 FIPS-202
Keccak keccak224, keccak256, keccak384, keccak512 Team Keccak
Blake2b blake2b160, blake2b256, blake2b384, blake2b512 RFC-7693
Blake2s blake2s128, blake2s160, blake2s224, blake2s256 RFC-7693
xxHash-32 XXHash32, xxh32, xxh32code Cyan4973
xxHash-64 XXHash64, xxh64, xxh64code Cyan4973
xxHash3-64 XXH3, xxh3, xxh3code Cyan4973
xxHash3-128 XXH128, xxh128, xxh128code Cyan4973
RIPEMD ripemd128, ripemd256, ripemd160, ripemd320 ISO/IEC 10118-3:2018
SM3 sm3, sm3sum GB/T 32905-2016

Note: XXHash64, XXH3, and XXH128 are not supported on the web platform. They throw UnimplementedError when used there.

Password / key derivation algorithms

Algorithm Available methods Source
Argon2 Argon2, argon2d, argon2i, argon2id, argon2Verify RFC-9106
PBKDF2 PBKDF2, pbkdf2, #.pbkdf2 RFC-8081
scrypt Scrypt, scrypt RFC-7914
bcrypt Bcrypt, bcrypt, bcryptSalt, bcryptVerify, bcryptDigest

Message authentication codes (MAC)

Algorithm Available methods Source
HMAC HMAC, #.hmac RFC-2104
Poly1305 Poly1305, poly1305, poly1305auth RFC-8439

One-time passwords (2FA)

Algorithm Available methods Source
HOTP HOTP RFC-4226
TOTP TOTP RFC-6238

Checksums

Algorithm Available methods Source
CRC crc16, crc32, crc64 Wikipedia
Adler-32 adler32 Wikipedia

Random and UUID

The random library provides random number generators through HashlibRandom (secure, system, keccak, sha256, md5, xxh64, sm3), plus helpers like randomBytes, randomNumbers, and randomString. UUID versions v1, v3, v4, v5, v6, v7, and v8 are available through uuid.

Security notes

  • Hash passwords with a KDF, not a bare hash. Store argon2id (or scrypt / bcrypt) output with an appropriate security preset — never a plain sha256 of a password — and check it with argon2Verify / bcryptVerify.
  • Compare digests in constant time. Use HashDigest.isEqual when verifying MACs and digests instead of == or a manual byte loop, to avoid leaking information through timing.
  • Legacy algorithms are for compatibility only. MD2, MD4, MD5, and SHA-1 are cryptographically broken; use them only for interop or non-security checksums, and prefer SHA-256, SHA-3, or BLAKE2 for new work.
  • Non-cryptographic hashes. CRC, Adler-32, and the xxHash family are fast integrity and lookup hashes, not secure against adversaries — do not use them where collision or preimage resistance matters.
  • Runtime timing. Pure-Dart execution (JIT, AOT, dart2js) is not guaranteed to run in constant time; weigh the deployment environment before relying on it in side-channel-sensitive settings.

Testing and reliability

Correctness is the first-order goal of this library, and the test suite is built to enforce it. There are 700 test cases across 60+ files` that runs after every change and before each release across three platforms: the Dart VM, Node.js, and Chrome (WASM).

Every algorithm is checked in several independent ways:

  • Official known-answer vectors. Digests are pinned against the published test vectors from the relevant standard — RFCs, FIPS/NIST publications, and each algorithm's reference implementation. Expected values are never invented; each vector cites its source in the test file.
  • Differential cross-validation. For every algorithm that a mature, independent Dart package also implements, the output is compared byte-for-byte against crypto and pointycastle over hundreds of random inputs. This currently covers MD2, MD4, MD5, SHA-1, SHA-224/256/384/512, SHA-512/224, SHA-512/256, SHA3 (224–512), Keccak (224–512), RIPEMD-128/160/256/320, BLAKE2b, SM3, and HMAC. A subtle divergence in padding, endianness, or a block boundary would fail these tests even if it slipped past a fixed vector.
  • Boundary and edge coverage. Inputs are exercised at the empty string, single bytes, and lengths straddling each algorithm's internal block/rate size (e.g. block−1, block, block+1, and multi-block messages) - the exact places where length-encoding and padding bugs hide.
  • Streaming equals one-shot. Chunked/streamed input and the incremental Sink API (including reset(), double-close(), and use-after-close) are verified to produce identical digests to the one-shot path.
  • Argument validation. Invalid key, salt, digest, and parameter lengths are asserted to throw typed errors rather than silently producing weak output.

The algorithms compute exactly what their standards define, verified against official vectors and multiple independent implementations. Please still read the Security notes above: choose the right primitive for your threat model (a KDF for passwords, a cryptographic hash rather than a checksum where an adversary is involved), and note that pure-Dart execution makes no hard constant-time guarantee.

You can reproduce all of this locally:

dart test              # vm, node, and chrome
dart test -p vm        # fast, VM-only iteration

Usage

Short, focused snippets follow — one per task. Every algorithm listed in the tables above plugs into the same calls, and full runnable programs live in the example folder.

Hash text or bytes

Turn any input into a fingerprint and read it in whatever format you need:

final digest = sha256.string('Happy Hashing!');

print(digest);           // hex string (the default when printed)
print(digest.hex());     // "d8d0..."  same value, explicit
print(digest.base64());  // Base64 encoding
digest.bytes;            // raw bytes as a Uint8List

sha256.convert([1, 2, 3]);      // hash a List<int> of bytes instead
sha256sum('Happy Hashing!');    // shortcut straight to a hex String

Swap sha256 for any hash — md5, sha3_256, blake2b512, sm3, and the rest all share this exact API.

Hash a large file or stream

Feed data in chunks instead of loading everything into memory. The result is identical to hashing it all at once:

final sink = sha256.createSink();
sink.add(firstChunk);   // each chunk is a List<int>
sink.add(nextChunk);
final digest = sink.digest();

Store and verify a password

Hash the password with a slow KDF and a fresh random salt, then store only the encoded result. To check a login, verify against that string — nothing is ever decrypted:

import 'package:hashlib/hashlib.dart';
import 'package:hashlib/random.dart'; // for randomBytes

// Sign-up: hash and store.
final salt = randomBytes(16);
final stored = argon2id(password.codeUnits, salt).encoded();
// stored => "$argon2id$v=19$m=65536,t=3,p=4$..."  safe to save in your database

// Login: check the password against the stored hash.
final ok = argon2Verify(stored, password.codeUnits); // true / false

bcrypt works the same way and generates its own salt:

final stored = bcrypt(password.codeUnits);
final ok = bcryptVerify(stored, password.codeUnits);

Both accept a security: preset (test, little, moderate, good, strong) that trades speed for resistance to guessing — pick the strongest your latency budget allows, e.g. argon2id(password.codeUnits, salt, security: Argon2Security.moderate).

Authenticate a message with a key (HMAC)

A MAC proves a message was not tampered with by anyone who does not know the shared key. Attach .hmac to any hash:

final tag = sha256.hmac.byString('shared-secret-key').string('transfer 100 coins');

// The receiver recomputes the tag and compares it in constant time:
final valid = tag.isEqual(receivedTag);

Compare tags with isEqual() (constant-time), never with == on the hex string — a plain comparison can leak the answer through timing.

Fast checksum for accidental corruption

Cheap integrity checks against bit-rot and transfer errors — not attackers:

crc32code('Happy Hashing!');   // => 3003384410 (an int)
adler32code('Happy Hashing!'); // another fast, non-secure checksum

One-time passwords (2FA)

final secret = 'my-shared-secret'.codeUnits;

TOTP(secret).value();                  // 6-digit code, rotates every 30 seconds
HOTP(secret, counter: counter).value(); // counter-based code (counter is bytes)

Secure random values and UUIDs

import 'package:hashlib/codecs.dart'; // for toHex
import 'package:hashlib/random.dart';

randomBytes(16);          // 16 cryptographically-secure bytes (great for a salt)
toHex(randomBytes(16));   // the same, as a hex string
randomString(32);         // a random text token
uuid.v4();                // a random UUID (v1/v3/v5/v6/v7/v8 also available)

Benchmarks

Libraries

Hash Functions

Algorithm Library 5MB message 1KB message 10B message
MD4 hashlib ████████████████
1.72 Gbps 🌟
████████████████
1.63 Gbps 🌟
████████████████
290 Mbps 🌟
PointyCastle ████████░░░░░░░░
915 Mbps 🔻1.88x
████████░░░░░░░░
864 Mbps 🔻1.89x
█████████░░░░░░░
169 Mbps 🔻1.72x
MD5 hashlib ████████████████
1.45 Gbps 🌟
████████████████
1.35 Gbps 🌟
████████████████
236 Mbps 🌟
crypto ███████████████░
1.36 Gbps 🔻1.07x
███████████████░
1.29 Gbps 🔻1.05x
███████████████░
228 Mbps 🔻1.04x
hash ██████████░░░░░░
920 Mbps 🔻1.58x
███████████░░░░░
929 Mbps 🔻1.45x
█████░░░░░░░░░░░
78.66 Mbps 🔻3x
PointyCastle █████████░░░░░░░
775 Mbps 🔻1.88x
█████████░░░░░░░
729 Mbps 🔻1.85x
██████████░░░░░░
141 Mbps 🔻1.68x
HMAC(MD5) hashlib ████████████████
1.45 Gbps 🌟
████████████████
1.1 Gbps 🌟
████████████░░░░
44.14 Mbps
crypto ███████████████░
1.34 Gbps 🔻1.08x
████████████████
1.1 Gbps 🔻1x
████████████████
58.31 Mbps 🔺1.32x
hash ██████████░░░░░░
913 Mbps 🔻1.59x
██████████░░░░░░
681 Mbps 🔻1.61x
██████░░░░░░░░░░
20.71 Mbps 🔻2.13x
SHA-1 hashlib ████████████████
1.27 Gbps 🌟
████████████████
1.17 Gbps 🌟
██████████████░░
155 Mbps
crypto ██████████████░░
1.12 Gbps 🔻1.14x
███████████████░
1.07 Gbps 🔻1.08x
████████████████
172 Mbps 🔺1.11x
PointyCastle ██████░░░░░░░░░░
502 Mbps 🔻2.53x
██████░░░░░░░░░░
472 Mbps 🔻2.47x
███████░░░░░░░░░
76.54 Mbps 🔻2.03x
hash ███████░░░░░░░░░
544 Mbps 🔻2.34x
███████░░░░░░░░░
534 Mbps 🔻2.18x
█████░░░░░░░░░░░
56.57 Mbps 🔻2.74x
HMAC(SHA-1) hashlib ████████████████
1.27 Gbps 🌟
████████████████
804 Mbps
█████████████░░░
21.87 Mbps
crypto ██████████████░░
1.13 Gbps 🔻1.13x
████████████████
818 Mbps 🔺1.02x
████████████████
26.98 Mbps 🔺1.23x
SHA-224 hashlib ████████████████
1.02 Gbps 🌟
████████████████
934 Mbps 🌟
████████████████
126 Mbps
crypto ███████████████░
932 Mbps 🔻1.1x
███████████████░
878 Mbps 🔻1.06x
████████████████
128 Mbps 🔺1.01x
hash ████░░░░░░░░░░░░
224 Mbps 🔻4.57x
████░░░░░░░░░░░░
231 Mbps 🔻4.04x
████░░░░░░░░░░░░
31.13 Mbps 🔻4.05x
PointyCastle ████░░░░░░░░░░░░
233 Mbps 🔻4.39x
████░░░░░░░░░░░░
222 Mbps 🔻4.2x
█████░░░░░░░░░░░
37.18 Mbps 🔻3.39x
SHA-256 hashlib ████████████████
1.02 Gbps 🌟
████████████████
945 Mbps 🌟
███████████████░
124 Mbps
crypto ███████████████░
929 Mbps 🔻1.1x
███████████████░
891 Mbps 🔻1.06x
████████████████
129 Mbps 🔺1.04x
hash ████░░░░░░░░░░░░
239 Mbps 🔻4.26x
████░░░░░░░░░░░░
234 Mbps 🔻4.04x
████░░░░░░░░░░░░
30.82 Mbps 🔻4.03x
PointyCastle ████░░░░░░░░░░░░
237 Mbps 🔻4.31x
████░░░░░░░░░░░░
220 Mbps 🔻4.3x
████░░░░░░░░░░░░
36.1 Mbps 🔻3.44x
HMAC(SHA-256) hashlib ████████████████
1.03 Gbps 🌟
████████████████
652 Mbps 🌟
██████████████░░
17.89 Mbps
crypto ███████████████░
943 Mbps 🔻1.09x
████████████████
649 Mbps 🔻1x
████████████████
20.79 Mbps 🔺1.16x
SHA-384 hashlib ████████████████
1.97 Gbps 🌟
████████████████
1.64 Gbps 🌟
████████████████
107 Mbps 🌟
crypto █████░░░░░░░░░░░
654 Mbps 🔻3x
██████░░░░░░░░░░
565 Mbps 🔻2.9x
███████░░░░░░░░░
48.35 Mbps 🔻2.22x
hash █░░░░░░░░░░░░░░░
175 Mbps 🔻11.26x
██░░░░░░░░░░░░░░
166 Mbps 🔻9.85x
██░░░░░░░░░░░░░░
14.86 Mbps 🔻7.23x
PointyCastle █░░░░░░░░░░░░░░░
51.87 Mbps 🔻37.9x
█░░░░░░░░░░░░░░░
45.78 Mbps 🔻35.79x
█░░░░░░░░░░░░░░░
3.98 Mbps 🔻26.98x
SHA-512 hashlib ████████████████
1.95 Gbps 🌟
████████████████
1.64 Gbps 🌟
████████████████
108 Mbps 🌟
crypto █████░░░░░░░░░░░
638 Mbps 🔻3.06x
█████░░░░░░░░░░░
561 Mbps 🔻2.93x
███████░░░░░░░░░
47.21 Mbps 🔻2.29x
hash █░░░░░░░░░░░░░░░
168 Mbps 🔻11.62x
██░░░░░░░░░░░░░░
164 Mbps 🔻10.02x
██░░░░░░░░░░░░░░
15 Mbps 🔻7.2x
PointyCastle █░░░░░░░░░░░░░░░
52.45 Mbps 🔻37.17x
█░░░░░░░░░░░░░░░
46.35 Mbps 🔻35.45x
█░░░░░░░░░░░░░░░
3.9 Mbps 🔻27.68x
SHA3-224 hashlib ████████████████
1.01 Gbps 🌟
████████████████
948 Mbps 🌟
████████████████
126 Mbps 🌟
PointyCastle █░░░░░░░░░░░░░░░
33.09 Mbps 🔻30.62x
█░░░░░░░░░░░░░░░
29.38 Mbps 🔻32.26x
█░░░░░░░░░░░░░░░
2.25 Mbps 🔻56.26x
SHA3-256 hashlib ████████████████
1.02 Gbps 🌟
████████████████
936 Mbps 🌟
████████████████
126 Mbps 🌟
PointyCastle █░░░░░░░░░░░░░░░
31.04 Mbps 🔻33.01x
█░░░░░░░░░░░░░░░
29.19 Mbps 🔻32.08x
█░░░░░░░░░░░░░░░
2.25 Mbps 🔻55.97x
SHA3-384 hashlib ████████████████
1.96 Gbps 🌟
████████████████
1.63 Gbps 🌟
████████████████
109 Mbps 🌟
PointyCastle █░░░░░░░░░░░░░░░
23.66 Mbps 🔻82.75x
█░░░░░░░░░░░░░░░
23.29 Mbps 🔻69.91x
█░░░░░░░░░░░░░░░
2.25 Mbps 🔻48.21x
SHA3-512 hashlib ████████████████
1.95 Gbps 🌟
████████████████
1.64 Gbps 🌟
████████████████
108 Mbps 🌟
PointyCastle █░░░░░░░░░░░░░░░
16.29 Mbps 🔻119.52x
█░░░░░░░░░░░░░░░
15.27 Mbps 🔻107.63x
█░░░░░░░░░░░░░░░
2.27 Mbps 🔻47.74x
RIPEMD-128 hashlib ████████████████
1.38 Gbps 🌟
████████████████
1.29 Gbps 🌟
████████████████
203 Mbps 🌟
PointyCastle ██████░░░░░░░░░░
478 Mbps 🔻2.89x
██████░░░░░░░░░░
448 Mbps 🔻2.87x
██████░░░░░░░░░░
80.7 Mbps 🔻2.52x
RIPEMD-160 hashlib ████████████████
734 Mbps 🌟
████████████████
700 Mbps 🌟
████████████████
110 Mbps 🌟
hash ████████░░░░░░░░
366 Mbps 🔻2.01x
████████░░░░░░░░
358 Mbps 🔻1.96x
███████░░░░░░░░░
45.18 Mbps 🔻2.44x
PointyCastle ███████░░░░░░░░░
333 Mbps 🔻2.2x
███████░░░░░░░░░
316 Mbps 🔻2.21x
████████░░░░░░░░
54.44 Mbps 🔻2.03x
RIPEMD-256 hashlib ████████████████
1.56 Gbps 🌟
████████████████
1.44 Gbps 🌟
████████████████
217 Mbps 🌟
PointyCastle █████░░░░░░░░░░░
471 Mbps 🔻3.31x
█████░░░░░░░░░░░
436 Mbps 🔻3.3x
██████░░░░░░░░░░
76.01 Mbps 🔻2.86x
RIPEMD-320 hashlib ████████████████
708 Mbps 🌟
████████████████
679 Mbps 🌟
████████████████
107 Mbps 🌟
PointyCastle ████████░░░░░░░░
337 Mbps 🔻2.1x
███████░░░░░░░░░
318 Mbps 🔻2.14x
████████░░░░░░░░
52.8 Mbps 🔻2.02x
BLAKE-2s hashlib ████████████████
1.67 Gbps 🌟
████████████████
1.65 Gbps 🌟
████████████████
208 Mbps 🌟
BLAKE-2b hashlib ████████████████
2.08 Gbps 🌟
████████████████
2.07 Gbps 🌟
████████████████
180 Mbps 🌟
PointyCastle █░░░░░░░░░░░░░░░
120 Mbps 🔻17.33x
█░░░░░░░░░░░░░░░
119 Mbps 🔻17.43x
█░░░░░░░░░░░░░░░
9.25 Mbps 🔻19.5x
Poly1305 hashlib ████████████████
4.61 Gbps 🌟
████████████████
4.48 Gbps 🌟
████████████████
680 Mbps 🌟
PointyCastle ████░░░░░░░░░░░░
1.29 Gbps 🔻3.57x
████░░░░░░░░░░░░
1.24 Gbps 🔻3.62x
████████░░░░░░░░
349 Mbps 🔻1.95x
XXH32 hashlib ████████████████
6 Gbps 🌟
████████████████
5.63 Gbps 🌟
████████████████
855 Mbps 🌟
XXH64 hashlib ████████████████
3.53 Gbps 🌟
████████████████
3.05 Gbps 🌟
████████████████
699 Mbps 🌟
XXH3 hashlib ████████████████
1.44 Gbps 🌟
████████████████
1.23 Gbps 🌟
████████████████
77.31 Mbps 🌟
XXH128 hashlib ████████████████
1.43 Gbps 🌟
████████████████
1.24 Gbps 🌟
████████████████
76.51 Mbps 🌟
SM3 hashlib ████████████████
955 Mbps 🌟
████████████████
885 Mbps 🌟
████████████████
142 Mbps 🌟
PointyCastle ████░░░░░░░░░░░░
245 Mbps 🔻3.89x
████░░░░░░░░░░░░
228 Mbps 🔻3.88x
████░░░░░░░░░░░░
37.45 Mbps 🔻3.8x

Key Derivators

Algorithm little moderate good strong
scrypt 1.02 ms 11.11 ms 61.04 ms 2007.44 ms
bcrypt 2.63 ms 20.57 ms 328.42 ms 2606.94 ms
pbkdf2 0.43 ms 13.96 ms 232.34 ms 2809.76 ms
argon2i 2.13 ms 14.69 ms 193.6 ms 2070.51 ms
argon2d 2.03 ms 14.54 ms 191.72 ms 2069.29 ms
argon2id 2.05 ms 14.52 ms 191.36 ms 2063.43 ms

All benchmarks are done on 36GB Apple M3 Pro using compiled exe

Dart SDK version: 3.12.2 (stable) (Tue Jun 9 01:11:39 2026 -0700) on "macos_arm64"

License

BSD 3-Clause License. See the LICENSE file for details. Issues and contributions are welcome at github.com/bitanon/hashlib.

About

Secure hash functions, checksum generators, and key derivation algorithms in pure Dart

Topics

Resources

Security policy

Stars

34 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages