Meziantou.Framework.Hashing 1.0.0

Meziantou.Framework.Hashing

Fully managed hash algorithms that the base class library does not provide, or does not provide on every platform:

The types are in the Meziantou.Framework.Hashing namespace. The SHA-3 types of System.Security.Cryptography use the cryptographic library of the operating system, which does not support them on every platform (e.g. macOS): the types of this package work everywhere.

This package replaces Meziantou.Framework.Bcrypt: the BCrypt types have the same names, in the Meziantou.Framework.Hashing namespace.

The implementations are tested against the test vectors of their specifications, but they have not been audited.

BCrypt

var hash = Bcrypt.HashPassword("my password");
var ok = Bcrypt.Verify("my password", hash);
Assert.True(ok);

You can select the BCrypt revision and cost (work factor):

var hash = Bcrypt.HashPassword(
    password: "my password",
    workFactor: 12,
    version: BcryptVersion.Revision2B);

var shouldRehash = Bcrypt.NeedsRehash(hash, workFactor: 13, version: BcryptVersion.Revision2B);
Assert.True(shouldRehash);

Supported revisions are:

• 2 ($2$) - verified only; salts cannot be generated
• 2a ($2a$)
• 2b ($2b$) - the default
• 2y ($2y$) - identical to $2b$

$2x$ is not supported. It exists only to reproduce the crypt_blowfish sign-extension bug, which this library does not emulate, so hashing or verifying a $2x$ hash throws NotSupportedException rather than silently mis-verifying passwords that contain non-ASCII characters. ParseHash still reads $2x$ hashes so you can find them in an existing database and re-hash those passwords.

BCrypt processes passwords as UTF-8 and uses at most 72 bytes.

Argon2

// A random salt of 16 bytes, stored next to the hash
var salt = RandomNumberGenerator.GetBytes(16);

// RFC 9106 section 4: Argon2id with 64 MiB of memory, 3 passes and 4 lanes
var hash = Argon2.DeriveBytes(Argon2Type.Argon2id, "my password"u8, salt, parallelism: 4, memorySizeInKiB: 64 * 1024, passes: 3, outputLength: 32);

// To verify a password, compute the hash with the same parameters and compare in constant time
var other = Argon2.DeriveBytes(Argon2Type.Argon2id, "my password"u8, salt, parallelism: 4, memorySizeInKiB: 64 * 1024, passes: 3, outputLength: 32);
Assert.True(CryptographicOperations.FixedTimeEquals(hash, other));

SHA-3 and SHAKE

var digest = Sha3.HashData(256, "abc"u8);
Assert.Equal("3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532", Convert.ToHexStringLower(digest));

SHAKE is an extendable-output function: the output can have any length. Pass a function name or a customization string to compute cSHAKE.

// SHAKE256 of "abc", 32 bytes of output
var output = Shake.HashData(256, "abc"u8, outputLength: 32);

// The same output, with the data appended and the output read in several parts
var shake = new Shake(256);
shake.AppendData("a"u8);
shake.AppendData("bc"u8);
var first = new byte[16];
var second = new byte[16];
shake.Read(first);
shake.Read(second);
Assert.Equal(output, first.Concat(second).ToArray());

Kmac, TurboShake and KangarooTwelve have the same shape: a HashData method that returns an array of the requested length, and an overload that fills a buffer.

BLAKE2b

// A digest of 32 bytes (BLAKE2b-256); the default size is 64 bytes (BLAKE2b-512)
var digest = Blake2b.HashData("abc"u8, hashSize: 32);

// The same digest, with the data appended in several parts
var blake2b = new Blake2b(hashSize: 32);
blake2b.AppendData("a"u8);
blake2b.AppendData("bc"u8);
Assert.Equal(digest, blake2b.GetHashAndReset());

Checksums

var crc = Crc32.Compute("123456789"u8);
Assert.Equal(0xCBF43926u, crc);

// The CRC of data received in several parts
var running = Crc32.Compute("1234"u8);
running = Crc32.Append(running, "56789"u8);
Assert.Equal(crc, running);

var checksum = Adler32.Compute("Wikipedia"u8);
Assert.Equal(0x11E60398u, checksum);

// The checksum of data received in several parts
var running = Adler32.Compute("Wiki"u8);
running = Adler32.Append(running, "pedia"u8);
Assert.Equal(checksum, running);

Crc32 and Adler32 use the vector and CRC instructions of the processor when they are available.