/++
DAuth - Authentication Utility for D
Core package

Main module: $(LINK2 index.html,dauth)$(BR)
+/
module dauth.core;

import std.algorithm;
import std.array;
import ascii = std.ascii;
import std.base64;
import std.conv;
import std.digest.crc;
import std.digest.md;
import std.digest.ripemd;
import std.digest.sha;
import std.exception;
import std.functional;
import std.random;
import std.range;
import std.typecons;

import dauth.random : randomSalt;
import dauth.sha;
import dauth.hashdrbg;

alias SHA1 = dauth.sha.SHA1;
alias SHA1Digest = dauth.sha.SHA1Digest;
alias sha1Of = dauth.sha.sha1Of;

version(DAuth_Unittest)
{
	version(DAuth_Unittest_Quiet) {} else
		version = Loud_Unittest;
	
	version(Loud_Unittest)
		import std.stdio;
	
	void unitlog(string str)
	{
		version(Loud_Unittest)
		{
			writeln("unittest DAuth: ", str);
			stdout.flush();
		}
	}
}

version(DAuth_AllowWeakSecurity) {} else
{
	version = DisallowWeakSecurity;
}

alias Salt = ubyte[]; /// Salt type
alias Salter(TDigest) = void delegate(ref TDigest, Password, Salt); /// Convenience alias for salter delegates.
alias DefaultCryptoRand = HashDRBGStream!(SHA512, "DAuth"); /// Default is Hash_DRBG using SHA-512
alias DefaultDigest = SHA512; /// Default is SHA-512
alias DefaultDigestClass = WrapperDigest!DefaultDigest; /// OO-style version of 'DefaultDigest'.
alias TokenBase64 = Base64Impl!('-', '_', '~'); /// Implementation of Base64 engine used for tokens.

/// Default implementation of 'digestCodeOfObj'.
/// See 'Hash!(TDigest).toString' for more info.
string defaultDigestCodeOfObj(Digest digest)
{
	if     (cast( CRC32Digest      )digest) return "CRC32";
	else if(cast( MD5Digest        )digest) return "MD5";
	else if(cast( RIPEMD160Digest  )digest) return "RIPEMD160";
	else if(cast( SHA1Digest       )digest) return "SHA1";
	else if(cast( SHA224Digest     )digest) return "SHA224";
	else if(cast( SHA256Digest     )digest) return "SHA256";
	else if(cast( SHA384Digest     )digest) return "SHA384";
	else if(cast( SHA512Digest     )digest) return "SHA512";
	else if(cast( SHA512_224Digest )digest) return "SHA512_224";
	else if(cast( SHA512_256Digest )digest) return "SHA512_256";
	else
		throw new UnknownDigestException("Unknown digest type");
}

/// Default implementation of 'digestCodeOfObj'.
/// See 'parseHash' for more info.
Digest defaultDigestFromCode(string digestCode)
{
	switch(digestCode)
	{
	case "CRC32":      return new CRC32Digest();
	case "MD5":        return new MD5Digest();
	case "RIPEMD160":  return new RIPEMD160Digest();
	case "SHA1":       return new SHA1Digest();
	case "SHA224":     return new SHA224Digest();
	case "SHA256":     return new SHA256Digest();
	case "SHA384":     return new SHA384Digest();
	case "SHA512":     return new SHA512Digest();
	case "SHA512_224": return new SHA512_224Digest();
	case "SHA512_256": return new SHA512_256Digest();
	default:
		throw new UnknownDigestException("Unknown digest code");
	}
}

/// Default salter for 'makeHash' and 'isPasswordCorrect'.
void defaultSalter(TDigest)(ref TDigest digest, Password password, Salt salt)
	if(isAnyDigest!TDigest)
{
	digest.put(cast(immutable(ubyte)[])salt);
	digest.put(password.data);
}

/++
Note, this only checks Phobos's RNG's and digests, and only by type. This
works on a blacklist basis - it blindly accepts any Phobos-compatible RNG
or digest it does not know about. This is only supplied as a convenience. It
is always your own responsibility to select an appropriate algorithm for your
own needs.

And yes, unfortunately, this does currently rule out all RNG's and digests
currently in Phobos (as of v2.065). They are all known to be fairly weak
for password-hashing purposes, even SHA1 which despite being heavily used
has known security flaws.

For random number generators, you should use a CPRNG (cryptographically secure
pseudorandom number generator):
    $(LINK http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator )

For digests, you should use one of the SHA-2 algorithms (for example, SHA512)
or, better yet, an established "key stretching" algorithm
( $(LINK http://en.wikipedia.org/wiki/Key_stretching#History) ), intended
for password hashing. These contain deliberate inefficiencies that cannot be
optimized away even with massive parallelization (such as a GPU cluster). These
are NOT too inefficient to use for even high-traffic authentication, but they
do thwart the parallelized brute force attacks that algorithms used for
streaming data encryption, such as SHA, are increasingly susceptible to.
    $(LINK https://crackstation.net/hashing-security.htm)
+/
bool isKnownWeak(T)() if(isDigest!T || isSomeRandom!T)
{
	return
		is(T == CRC32) ||
		is(T == MD5) ||
		is(T == RIPEMD160) ||
		is(T == SHA1) ||
		
		// Requires to-be-released DMD 2.066:
		//__traits(isSame, TemplateOf!T, LinearCongruentialEngine) ||
		//__traits(isSame, TemplateOf!T, MersenneTwisterEngine) ||
		//__traits(isSame, TemplateOf!T, XorshiftEngine);
		is(T == MinstdRand0) ||
		is(T == MinstdRand) ||
		is(T == Mt19937) ||
		is(T == Xorshift32) ||
		is(T == Xorshift64) ||
		is(T == Xorshift96) ||
		is(T == Xorshift128) ||
		is(T == Xorshift160) ||
		is(T == Xorshift192) ||
		is(T == Xorshift);
}

///ditto
bool isKnownWeak(T)(T digest) if(is(T : Digest))
{
	return
		cast(CRC32Digest)digest ||
		cast(MD5Digest)digest ||
		cast(RIPEMD160Digest)digest ||
		cast(SHA1Digest)digest;
}

private void validateStrength(T)() if(isDigest!T || isSomeRandom!T)
{
	version(DisallowWeakSecurity)
	{
		static if(isKnownWeak!T())
		{
			pragma(msg, "ERROR: "~T.stringof~" - "~KnownWeakException.message);
			static assert(false);
		}
	}
}

private void validateStrength(Digest digest)
{
	version(DisallowWeakSecurity)
	{
		enforce(!isKnownWeak(digest),
			new KnownWeakException(defaultDigestCodeOfObj(digest)));
	}
}

/// Thrown whenever a digest type cannot be determined.
/// For example, when the provided (or default) 'digestCodeOfObj' or 'digestFromCode'
/// delegates fail to find a match. Or when passing isPasswordCorrect a
/// Hash!Digest with a null 'digest' member (which prevents it from determining
/// the correct digest to match with).
class UnknownDigestException : Exception
{
	this(string msg) { super(msg); }
}

/// Thrown when a known-weak algortihm or setting it attempted, UNLESS
/// compiled with '-version=DAuth_AllowWeakSecurity'
class KnownWeakException : Exception
{
	static enum message =
		"This is known to be weak for salted password hashing. "~
		"If you understand and accept the risks, you can force DAuth "~
		"to allow it with -version=DAuth_AllowWeakSecurity";
	
	this(string algoName)
	{
		super(algoName ~ " - " ~ message);
	}
}

/// Like std.digest.digest.isDigest, but also accepts OO-style digests
/// (ie. classes deriving from interface std.digest.digest.Digest)
template isAnyDigest(TDigest)
{
	enum isAnyDigest =
		isDigest!TDigest ||
		is(TDigest : Digest);
}

version(DAuth_Unittest)
unittest
{
	struct Foo {}
	static assert(isAnyDigest!SHA1);
	static assert(isAnyDigest!SHA1Digest);
	static assert(isAnyDigest!SHA256);
	static assert(isAnyDigest!SHA256Digest);
	static assert(!isAnyDigest!Foo);
	static assert(!isAnyDigest!Object);
}

/// Like std.digest.digest.DigestType, but also accepts OO-style digests
/// (ie. classes deriving from interface std.digest.digest.Digest)
template AnyDigestType(TDigest)
{
	static assert(isAnyDigest!TDigest,
		TDigest.stringof ~ " is not a template-style or OO-style digest (fails isAnyDigest!T)");
	
	static if(isDigest!TDigest)
		alias AnyDigestType = DigestType!TDigest;
	else
		alias AnyDigestType = ubyte[];
}

version(DAuth_Unittest)
unittest
{
	struct Foo {}
	static assert( is(AnyDigestType!SHA1 == ubyte[20]) );
	static assert( is(AnyDigestType!SHA1Digest == ubyte[]) );
	static assert( is(AnyDigestType!SHA512 == ubyte[64]) );
	static assert( is(AnyDigestType!SHA512Digest == ubyte[]) );
	static assert( !is(AnyDigestType!Foo) );
	static assert( !is(AnyDigestType!Object) );
}

/// Tests if the type is an instance of struct Hash(some digest)
template isHash(T)
{
	enum isHash = is( Hash!(TemplateArgsOf!(T)[0]) == T );
}

version(DAuth_Unittest)
unittest
{
	struct Foo {}
	struct Bar(T) { T digest; }

	static assert( isHash!(Hash!SHA1) );
	static assert( isHash!(Hash!SHA1Digest) );
	static assert( isHash!(Hash!SHA512) );
	static assert( isHash!(Hash!SHA512Digest) );

	static assert( !isHash!Foo              );
	static assert( !isHash!(Bar!int)        );
	static assert( !isHash!(Bar!Object)     );
	static assert( !isHash!(Bar!SHA1)       );
	static assert( !isHash!(Bar!SHA1Digest) );
}

/// Retreive the digest type of a struct Hash(some digest)
template DigestOf(T) if(isHash!T)
{
	alias DigestOf = TemplateArgsOf!(T)[0];
}

version(DAuth_Unittest)
unittest
{
	static assert(is( DigestOf!(Hash!SHA1  ) == SHA1  ));
	static assert(is( DigestOf!(Hash!SHA512) == SHA512));
	static assert(is( DigestOf!(Hash!Digest) == Digest));
}

string getDigestCode(TDigest)(string delegate(Digest) digestCodeOfObj, TDigest digest)
	if(isAnyDigest!TDigest)
{
	static if(is(TDigest : Digest))
		return digestCodeOfObj(digest);
	else
	{
		auto digestObj = new WrapperDigest!TDigest();
		return digestCodeOfObj(digestObj);
	}
}

/++
A reference-counted type for passwords. The memory containing the password
is automatically zeroed-out when there are no more references or when
a new password is assigned.

If you keep any direct references to Password.data, be aware it may get cleared.

The payload is a private struct that supports the following:

	@property ubyte[] data(): Retrieve the actual plaintext password

	@property size_t length() const: Retrieve the password length

	void opAssign(PasswordData rhs): Assignment

	void opAssign(ubyte[] rhs): Assignment

	~this(): Destructor
+/
alias Password = RefCounted!PasswordData;

/// Payload of Password
private struct PasswordData
{
	private ubyte[] _data;
	
	@property ubyte[] data()
	{
		return _data;
	}
	
	@property size_t length() const
	{
		return _data.length;
	}
	
	void opAssign(PasswordData rhs)
	{
		opAssign(rhs._data);
	}
	
	void opAssign(ubyte[] rhs)
	{
		clear();
		this._data = rhs;
	}
	
	~this()
	{
		clear();
	}

	private void clear()
	{
		_data[] = 0;
	}
}

/// Constructs a Password from a ubyte[].
/// Mainly provided for syntactic consistency with 'toPassword(char[])'.
Password toPassword(ubyte[] password)
{
	return Password(password);
}

/// Constructs a Password from a char[] so you don't have to cast to ubyte[],
/// and don't accidentally cast away immutability.
Password toPassword(char[] password)
{
	return Password(cast(ubyte[])password);
}

/// This function exists as a convenience in case you need it, HOWEVER it's
/// recommended to design your code so you DON'T need to use this (use
/// toPassword instead):
///
/// Using this to create a Password cannot protect the in-memory data of your
/// original string because a string's data is immutable (this function must
/// .dup the memory).
///
/// While immutability usually improves safety, you should avoid ever storing
/// unhashed passwords in immutables because they cannot be reliably
/// zero-ed out.
Password dupPassword(string password)
{
	return toPassword(password.dup);
}

/// Contains all the relevant information for a salted hash.
/// Note the digest type can be obtained via DigestOf!(SomeHashType).
struct Hash(TDigest) if(isAnyDigest!TDigest)
{
	Salt salt; /// The salt that was used.
	
	/// The hash of the salted password. To obtain a printable DB-friendly
	/// string, pass this to std.digest.digest.toHexString.
	AnyDigestType!TDigest hash;
	
	/// The digest that was used for hashing.
	TDigest digest;
	
	/// Encodes the digest, salt and hash into a convenient forward-compatible
	/// string format, ready for insertion into a database.
	///
	/// To support additional digests besides the built-in (Phobos's CRC32, MD5,
	/// RIPEMD160 and SHA), supply a custom delegate for digestCodeOfObj.
	/// Your custom digestCodeOfObj only needs to handle OO-style digests.
	/// As long as the OO-style digests were created using Phobos's
	/// WrapperDigest template, the template-style version will be handled
	/// automatically. You can defer to DAuth's defaultDigestCodeOfObj to
	/// handle the built-in digests.
	///
	/// Example:
	/// -------------------
	/// import std.digest.digest;
	/// import dauth;
	/// 
	/// struct BBQ42 {...}
	/// static assert(isDigest!BBQ42);
	/// alias BBQ42Digest = WrapperDigest!BBQ42;
	/// 
	/// string customDigestCodeOfObj(Digest digest)
	/// {
	///     if     (cast(BBQ42Digest)digest) return "BBQ42";
	///     else if(cast(FAQ17Digest)digest) return "FAQ17";
	///     else
	///         return defaultDigestCodeOfObj(digest);
	/// }
	/// 
	/// void doStuff(Hash!BBQ42 hash)
	/// {
	///     writeln( hash.toString(&customDigestCodeOfObj) );
	/// }
	/// -------------------
	string toString(string delegate(Digest) digestCodeOfObj = toDelegate(&defaultDigestCodeOfObj))
	{
		Appender!string sink;
		toString(sink, digestCodeOfObj);
		return sink.data;
	}

	///ditto
	void toString(Sink)(ref Sink sink,
		string delegate(Digest) digestCodeOfObj = toDelegate(&defaultDigestCodeOfObj))
		if(isOutputRange!(Sink, const(char)))
	{
		sink.put('[');
		sink.put(getDigestCode(digestCodeOfObj, digest));
		sink.put(']');
		Base64.encode(salt, sink);
		sink.put('$');
		Base64.encode(hash, sink);
	}
}

/++
Generates a salted password using any Phobos-compatible digest, default being SHA-512.

(Note: An established "key stretching" algorithm
( $(LINK http://en.wikipedia.org/wiki/Key_stretching#History) ) would be an even
better choice of digest since they provide better protection against
highly-parallelized (ex: GPU) brute-force attacks. But SHA-512, as an SHA-2
algorithm, is still considered cryptographically secure.)

Supports both template-style and OO-style digests. See the documentation of
std.digest.digest for details.

Salt is optional. It will be generated at random if not provided.

Normally, the salt and password are combined as (psuedocode) 'salt~password'.
There is no cryptographic benefit to combining the salt and password any
other way. However, if you need to support an alternate method for
compatibility purposes, you can do so by providing a custom salter delegate.
See the implementation of DAuth's defaultSalter to see how to do this.

If using an OO-style Digest, then digest MUST be non-null. Otherwise,
an UnknownDigestException will be thrown.
+/
Hash!TDigest makeHash(TDigest = DefaultDigest)
	(Password password, Salt salt = randomSalt(), Salter!TDigest salter = toDelegate(&defaultSalter!TDigest))
	if(isDigest!TDigest)
{
	validateStrength!TDigest();
	TDigest digest;
	return makeHashImpl!TDigest(digest, password, salt, salter);
}

///ditto
Hash!TDigest makeHash(TDigest = DefaultDigest)(Password password, Salter!TDigest salter)
	if(isDigest!TDigest)
{
	validateStrength!TDigest();
	TDigest digest;
	return makeHashImpl(digest, password, randomSalt(), salter);
}

///ditto
Hash!Digest makeHash()(Digest digest, Password password, Salt salt = randomSalt(),
	Salter!Digest salter = toDelegate(&defaultSalter!Digest))
{
	enforce(digest, new UnknownDigestException("digest was null, don't know what digest to use"));
	validateStrength(digest);
	return makeHashImpl!Digest(digest, password, salt, salter);
}

///ditto
Hash!Digest makeHash()(Digest digest, Password password, Salter!Digest salter)
{
	enforce(digest, new UnknownDigestException("digest was null, don't know what digest to use"));
	validateStrength(digest);
	return makeHashImpl!Digest(digest, password, randomSalt(), salter);
}

private Hash!TDigest makeHashImpl(TDigest)
	(ref TDigest digest, Password password, Salt salt, Salter!TDigest salter)
	if(isAnyDigest!TDigest)
{
	Hash!TDigest ret;
	ret.digest = digest;
	ret.salt   = salt;
	
	static if(isDigest!TDigest) // template-based digest
		ret.digest.start();
	else
		ret.digest.reset(); // OO-based digest
	
	salter(ret.digest, password, salt);
	ret.hash = ret.digest.finish();
	
	return ret;
}

/// Parses a string that was encoded by Hash.toString.
///
/// Only OO-style digests are used since the digest is specified in the string
/// and therefore only known at runtime.
///
/// Throws ConvException if the string is malformed.
///
/// To support additional digests besides the built-in (Phobos's CRC32, MD5,
/// RIPEMD160 and SHA), supply a custom delegate for digestFromCode.
/// You can defer to DAuth's defaultDigestFromCode to handle the
/// built-in digests.
///
/// Example:
/// -------------------
/// import std.digest.digest;
/// import dauth;
/// 
/// struct BBQ42 {...}
/// static assert(isDigest!BBQ42);
/// alias BBQ42Digest = WrapperDigest!BBQ42;
/// 
/// Digest customDigestFromCode(string digestCode)
/// {
///     switch(digestCode)
///     {
///     case "BBQ42": return new BBQ42Digest();
///     case "FAQ17": return new FAQ17Digest();
///     default:
///         return defaultDigestFromCode(digestCode);
///     }
/// }
/// 
/// void doStuff(string hashString)
/// {
///     auto hash = parseHash(hashString, &customDigestFromCode);
/// }
/// -------------------
Hash!Digest parseHash(string str,
	Digest delegate(string) digestFromCode = toDelegate(&defaultDigestFromCode))
{
	// No need to mess with UTF
	auto bytes = cast(immutable(ubyte)[]) str;
	
	// Parse '['
	enforceEx!ConvException(!bytes.empty);
	enforceEx!ConvException(bytes.front == cast(ubyte)'[');
	bytes.popFront();

	// Parse digest code
	auto splitRBracket = bytes.findSplit([']']);
	enforceEx!ConvException( !splitRBracket[0].empty && !splitRBracket[1].empty && !splitRBracket[2].empty );
	auto digestCode = splitRBracket[0];
	bytes = splitRBracket[2];
	
	// Split salt and hash
	auto splitDollar = bytes.findSplit(['$']);
	enforceEx!ConvException( !splitDollar[0].empty && !splitDollar[1].empty && !splitDollar[2].empty );
	auto salt = splitDollar[0];
	auto hash = splitDollar[2];
	
	// Construct Hash
	Hash!Digest result;
	result.salt   = Base64.decode(salt);
	result.hash   = Base64.decode(hash);
	result.digest = digestFromCode(cast(string)digestCode);
	
	return result;
}

/// Validates a password against an existing salted hash.
///
/// If sHash is a Hash!Digest, then sHash.digest MUST be non-null. Otherwise
/// this function will have no other way to determine what digest to match
/// against, and an UnknownDigestException will be thrown.
bool isPasswordCorrect(TDigest = DefaultDigest)(Password password, Hash!TDigest sHash,
	Salter!TDigest salter = toDelegate(&defaultSalter!TDigest))
	if(isDigest!TDigest)
{
	auto testHash = makeHash!TDigest(password, sHash.salt, salter);
	return lengthConstantEquals(testHash.hash, sHash.hash);
}

///ditto
bool isPasswordCorrect(TDigest = Digest)(Password password, Hash!TDigest sHash,
	Salter!Digest salter = toDelegate(&defaultSalter!Digest))
	if(is(TDigest : Digest))
{
	Hash!Digest testHash;

	if(sHash.digest)
		testHash = makeHash(sHash.digest, password, sHash.salt, salter);
	else
	{
		static if(is(TDigest == Digest))
			throw new UnknownDigestException("Cannot determine digest from a Hash!Digest with a null 'digest' member.");
		else
			testHash = makeHash(new TDigest(), password, sHash.salt, salter);
	}

	return lengthConstantEquals(testHash.hash, sHash.hash);
}

///ditto
bool isPasswordCorrect(TDigest = DefaultDigest)
	(Password password, DigestType!TDigest hash, Salt salt,
		Salter!TDigest salter = toDelegate(&defaultSalter!TDigest))
	if(isDigest!TDigest)
{
	auto testHash = makeHash!TDigest(password, salt, salter);
	return lengthConstantEquals(testHash.hash, hash);
}

///ditto
bool isPasswordCorrect()(Password password,
	ubyte[] hash, Salt salt, Digest digest = new DefaultDigestClass(),
	Salter!Digest salter = toDelegate(&defaultSalter!Digest))
{
	auto testHash = makeHash(digest, password, salt, salter);
	return lengthConstantEquals(testHash.hash, hash);
}

///ditto
bool isPasswordCorrect()(Password password,
	ubyte[] hash, Salt salt, Salter!Digest salter)
{
	auto testHash = makeHash(new DefaultDigestClass(), password, salt, salter);
	return lengthConstantEquals(testHash.hash, hash);
}

version(DAuth_Unittest)
unittest
{
	// For validity of sanity checks, these sha and base64 strings
	// were NOT generated using Phobos.
	auto plainText1        = dupPassword("hello world");
	enum sha1Hash1         = cast(ubyte[20]) x"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed";
	enum sha1Hash1Base64   = "Kq5sNclPz7QV2+lfQIuc6R7oRu0=";
	enum sha512Hash1       = cast(ubyte[64]) x"309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f";
	enum sha512Hash1Base64 = "MJ7MSJwS1utMxA9QyQLytNDtd+5RGnx6m808qG1M2G+YndNbxf9JlnDaNCVbRbDP2DDoH2Bdz33FVC6TrpzXbw==";

	auto plainText2        = dupPassword("some salt");
	enum sha1Hash2         = cast(ubyte[20]) x"78bc8b0e186b0aa698f12dc27736b492e4dacfc8";
	enum sha1Hash2Base64   = "eLyLDhhrCqaY8S3Cdza0kuTaz8g=";
	enum sha512Hash2       = cast(ubyte[64]) x"637246608760dc79f00d3ad4fd26c246bb217e10f811cdbf6fe602c3981e98b8cadacadc452808ae393ac46e8a7e967aa99711d7fd7ed6c055264787f8043693";
	enum sha512Hash2Base64 = "Y3JGYIdg3HnwDTrU/SbCRrshfhD4Ec2/b+YCw5gemLjK2srcRSgIrjk6xG6KfpZ6qZcR1/1+1sBVJkeH+AQ2kw==";
	
	unitlog("Sanity checking unittest's data");
	assert(sha1Of(plainText1.data) == sha1Hash1);
	assert(sha1Of(plainText2.data) == sha1Hash2);
	assert(sha512Of(plainText1.data) == sha512Hash1);
	assert(sha512Of(plainText2.data) == sha512Hash2);
	assert(Base64.encode(sha1Hash1) == sha1Hash1Base64);
	assert(Base64.encode(sha1Hash2) == sha1Hash2Base64);
	assert(Base64.encode(sha512Hash1) == sha512Hash1Base64);
	assert(Base64.encode(sha512Hash2) == sha512Hash2Base64);

	unitlog("Testing Hash.toString");
	Hash!SHA1 result1;
	result1.hash = cast(AnyDigestType!SHA1) sha1Hash1;
	result1.salt = cast(Salt)               sha1Hash2;
	assert( result1.toString() == text("[SHA1]", sha1Hash2Base64, "$", sha1Hash1Base64) );

	Hash!SHA512 result1_512;
	result1_512.hash = cast(AnyDigestType!SHA512) sha512Hash1;
	result1_512.salt = cast(Salt)                 sha512Hash2;
	assert( result1_512.toString() == text("[SHA512]", sha512Hash2Base64, "$", sha512Hash1Base64) );
	
	unitlog("Testing makeHash([digest,] pass, salt [, salter])");
	void altSalter(TDigest)(ref TDigest digest, Password password, Salt salt)
	{
		// Reverse order
		digest.put(password.data);
		digest.put(cast(immutable(ubyte)[])salt);
	}
	
	auto result2          = makeHash!SHA1(plainText1, cast(Salt)sha1Hash2[]);
	auto result2AltSalter = makeHash!SHA1(plainText1, cast(Salt)sha1Hash2[], &altSalter!SHA1);
	auto result3          = makeHash(new SHA1Digest(), plainText1, cast(Salt)sha1Hash2[]);
	auto result3AltSalter = makeHash(new SHA1Digest(), plainText1, cast(Salt)sha1Hash2[], &altSalter!Digest);

	assert(result2.salt       == result3.salt);
	assert(result2.hash       == result3.hash);
	assert(result2.toString() == result3.toString());
	assert(result2.toString() == makeHash!SHA1(plainText1, cast(Salt)sha1Hash2[]).toString());
	assert(result2.salt == result1.salt);

	assert(result2AltSalter.salt       == result3AltSalter.salt);
	assert(result2AltSalter.hash       == result3AltSalter.hash);
	assert(result2AltSalter.toString() == result3AltSalter.toString());
	assert(result2AltSalter.toString() == makeHash!SHA1(plainText1, cast(Salt)sha1Hash2[], &altSalter!SHA1).toString());
	
	assert(result2.salt       == result2AltSalter.salt);
	assert(result2.hash       != result2AltSalter.hash);
	assert(result2.toString() != result2AltSalter.toString());

	auto result2_512          = makeHash!SHA512(plainText1, cast(Salt)sha512Hash2[]);
	auto result2_512AltSalter = makeHash!SHA512(plainText1, cast(Salt)sha512Hash2[], &altSalter!SHA512);
	auto result3_512          = makeHash(new SHA512Digest(), plainText1, cast(Salt)sha512Hash2[]);
	auto result3_512AltSalter = makeHash(new SHA512Digest(), plainText1, cast(Salt)sha512Hash2[], &altSalter!Digest);

	assert(result2_512.salt       == result3_512.salt);
	assert(result2_512.hash       == result3_512.hash);
	assert(result2_512.toString() == result3_512.toString());
	assert(result2_512.toString() == makeHash!SHA512(plainText1, cast(Salt)sha512Hash2[]).toString());
	assert(result2_512.salt == result1_512.salt);

	assert(result2_512AltSalter.salt       == result3_512AltSalter.salt);
	assert(result2_512AltSalter.hash       == result3_512AltSalter.hash);
	assert(result2_512AltSalter.toString() == result3_512AltSalter.toString());
	assert(result2_512AltSalter.toString() == makeHash!SHA512(plainText1, cast(Salt)sha512Hash2[], &altSalter!SHA512).toString());
	
	assert(result2_512.salt       == result2_512AltSalter.salt);
	assert(result2_512.hash       != result2_512AltSalter.hash);
	assert(result2_512.toString() != result2_512AltSalter.toString());
	
	assertThrown!UnknownDigestException( makeHash(cast(SHA1Digest)null, plainText1, cast(Salt)sha1Hash2[]) );
	assertThrown!UnknownDigestException( makeHash(cast(Digest)null,     plainText1, cast(Salt)sha1Hash2[]) );

	unitlog("Testing makeHash(pass)");
	import dauth.random : randomPassword;
	auto resultRand1 = makeHash!SHA1(randomPassword());
	auto resultRand2 = makeHash!SHA1(randomPassword());

	assert(resultRand1.salt != result1.salt);

	assert(resultRand1.salt != resultRand2.salt);
	assert(resultRand1.hash != resultRand2.hash);

	unitlog("Testing parseHash(void)");
	auto result2Parsed = parseHash( result2.toString() );
	assert(result2.salt       == result2Parsed.salt);
	assert(result2.hash       == result2Parsed.hash);
	assert(result2.toString() == result2Parsed.toString());

	assert(makeHash(result2Parsed.digest, plainText1, result2Parsed.salt) == result2Parsed);
	
	unitlog("Testing isPasswordCorrect");
	assert(isPasswordCorrect     (plainText1, result2));
	assert(isPasswordCorrect!SHA1(plainText1, result2.hash, result2.salt));
	assert(isPasswordCorrect     (plainText1, result2.hash, result2.salt, new SHA1Digest()));

	assert(isPasswordCorrect!SHA1(plainText1, result2AltSalter, &altSalter!SHA1));
	assert(isPasswordCorrect!SHA1(plainText1, result2AltSalter.hash, result2AltSalter.salt, &altSalter!SHA1));
	assert(isPasswordCorrect     (plainText1, result2AltSalter.hash, result2AltSalter.salt, new SHA1Digest(), &altSalter!Digest));

	assert(!isPasswordCorrect     (dupPassword("bad pass"), result2));
	assert(!isPasswordCorrect!SHA1(dupPassword("bad pass"), result2.hash, result2.salt));
	assert(!isPasswordCorrect     (dupPassword("bad pass"), result2.hash, result2.salt, new SHA1Digest()));

	assert(!isPasswordCorrect!SHA1(dupPassword("bad pass"), result2AltSalter, &altSalter!SHA1));
	assert(!isPasswordCorrect!SHA1(dupPassword("bad pass"), result2AltSalter.hash, result2AltSalter.salt, &altSalter!SHA1));
	assert(!isPasswordCorrect     (dupPassword("bad pass"), result2AltSalter.hash, result2AltSalter.salt, new SHA1Digest(), &altSalter!Digest));
	
	Hash!SHA1Digest ooHashSHA1Digest;
	ooHashSHA1Digest.salt = result2.salt;
	ooHashSHA1Digest.hash = result2.hash;
	ooHashSHA1Digest.digest = new SHA1Digest();
	assert( isPasswordCorrect(plainText1, ooHashSHA1Digest) );
	ooHashSHA1Digest.digest = null;
	assert( isPasswordCorrect(plainText1, ooHashSHA1Digest) );
	
	Hash!Digest ooHashDigest;
	ooHashDigest.salt = result2.salt;
	ooHashDigest.hash = result2.hash;
	ooHashDigest.digest = new SHA1Digest();
	assert( isPasswordCorrect(plainText1, ooHashDigest) );
	ooHashDigest.digest = null;
	assertThrown!UnknownDigestException( isPasswordCorrect(plainText1, ooHashDigest) );
	
	assert( isPasswordCorrect(plainText1, parseHash(result2.toString())) );

	auto wrongSalt = result2;
	wrongSalt.salt = wrongSalt.salt[4..$-1];
	
	assert(!isPasswordCorrect     (plainText1, wrongSalt));
	assert(!isPasswordCorrect!SHA1(plainText1, wrongSalt.hash, wrongSalt.salt));
	assert(!isPasswordCorrect     (plainText1, wrongSalt.hash, wrongSalt.salt, new SHA1Digest()));

	Hash!MD5 wrongDigest;
	wrongDigest.salt = result2.salt;
	wrongDigest.hash = cast(ubyte[16])result2.hash[0..16];
	
	assert(!isPasswordCorrect    (plainText1, wrongDigest));
	assert(!isPasswordCorrect!MD5(plainText1, wrongDigest.hash, wrongDigest.salt));
	assert(!isPasswordCorrect    (plainText1, wrongDigest.hash, wrongDigest.salt, new MD5Digest()));
}

/++
Compare two arrays in "length-constant" time. This thwarts timing-based
attacks by guaranteeing all comparisons (of a given length) take the same
amount of time.

See the section "Why does the hashing code on this page compare the hashes in
"length-constant" time?" at:
    $(LINK https://crackstation.net/hashing-security.htm)
+/
bool lengthConstantEquals(ubyte[] a, ubyte[] b)
{
	auto diff = a.length ^ b.length;
	for(int i = 0; i < a.length && i < b.length; i++)
		diff |= a[i] ^ b[i];

	return diff == 0;
}

// Borrowed from Phobos master (Should arrive in DMD v2.066).
package template TemplateArgsOf(alias T : Base!Args, alias Base, Args...)
{
    alias TemplateArgsOf = Args;
}
package template TemplateArgsOf(T : Base!Args, alias Base, Args...)
{
    alias TemplateArgsOf = Args;
}
static assert(is( TemplateArgsOf!( Hash!SHA1   )[0] == SHA1   ));
static assert(is( TemplateArgsOf!( Hash!Digest )[0] == Digest ));