path: root/include/modules/hash.h

/*
 * InspIRCd -- Internet Relay Chat Daemon
 *
 *   Copyright (C) 2025 Sadie Powell <sadie@witchery.services>
 *
 * This file is part of InspIRCd.  InspIRCd is free software: you can
 * redistribute it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation, version 2.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */


#pragma once

#include "stringutils.h"
#include "utility/string.h"

namespace Hash
{
	class Context;
	class Provider;
	class ProviderRef;
	class HMACContext;
	class HMACProvider;

	/** Compares a password to a hashed password.
	 * @param password The hashed password.
	 * @param algorithm If non-empty then the algorithm the password is hashed with.
	 * @param value The value to check to see if the password is valid.
	 * @return True if the password is correct, otherwise, false.
	 */
	inline bool CheckPassword(const std::string& password, const std::string& algorithm, const std::string& value);

	/** Generates a hash-based message authentication code.
	 * @param prov The hash algorithm to hash with.
	 * @param key The secret key.
	 * @param data The data to hash.
	 */
	inline std::string HMAC(Hash::Provider* prov, const std::string& key, const std::string& data);
}


/** Base class for hash contexts. */
class Hash::Context
{
public:
	virtual ~Context() = default;

	/** Updates the hash context with the specified data.
	 * @param str The data to update the context with.
	 */
	inline void Update(const std::string& str)
	{
		Update(reinterpret_cast<const unsigned char *>(str.c_str()), str.length());
	}

	/** Updates the hash context with the specified data.
	 * @param data The data to update the context with.
	 * @param len The length of the data.
	 */
	virtual void Update(const unsigned char *data, size_t len) = 0;

	/** Finalises the hash context and returns the digest. */
	virtual std::string Finalize() = 0;
};

/** Provider of hash contexts. */
class Hash::Provider
	: public DataProvider
{
public:
	/** The byte size of the block cipher. */
	const size_t block_size;

	/** The byte size of the resulting digest. */
	const size_t digest_size;

	/** Creates a provider of hash contexts.
	 * @param mod The module that created this provider.
	 * @param algorithm The name of the hash algorithm.
	 * @param ds The byte size of the resulting digest or 0 if it is variable length.
	 * @param bs The byte size of the block cipher or 0 if not a block cipher.
	 */
	Provider(Module* mod, const std::string& algorithm, size_t ds = 0, size_t bs = 0)
		: DataProvider(mod, "hash/" + algorithm)
		, block_size(bs)
		, digest_size(ds)
	{
	}

	virtual ~Provider() = default;

	/** Checks whether a plain text value matches a hash created by this provider
	 * @param hash The hashed value to compare against.
	 * @param plain The plain text password to compare.
	 */
	virtual bool Compare(const std::string& hash, const std::string& plain)
	{
		return !hash.empty() && InspIRCd::TimingSafeCompare(hash, ToPrintable(Hash(plain)));
	}

	/** Called on initialising a hash provider to check it works properly.
	 * @param checks A map of known ciphertexts to plaintexts.
	 */
	inline void Check(const std::map<std::string, std::string>& checks)
	{
		for (const auto& [hash, plain] : checks)
		{
			if (!Compare(hash, plain))
				throw ModuleException(creator, "BUG: unable to generate {} hashes safely! Please report this!", GetAlgorithm());
		}

		ServerInstance->Logs.Debug("HASH", "The {} hash provider appears to be working correctly.", GetAlgorithm());
	}

	/** Creates a new hash context. */
	virtual std::unique_ptr<Context> CreateContext() = 0;

	/** Retrieves the name of the hash algorithm. */
	const char* GetAlgorithm() const
	{
		return name.c_str() + 5;
	}

	/** Quickly hashes the specified values and returns the digest. */
	template<typename... Args>
	std::string Hash(Args&& ...args)
	{
		auto context = CreateContext();
		context->Update(std::forward<Args>(args)...);
		return context->Finalize();
	}

	/** Determines whether this hash algorithm is a key derivation function. */
	auto IsKDF() const { return block_size == 0; }

	/** Determines whether this hash provider is safe for password hashing. */
	virtual bool IsPasswordSafe() const { return true; }

	/** Converts a hash to its printable form. */
	virtual std::string ToPrintable(const std::string& hash)
	{
		return Hex::Encode(hash);
	}
};

/** Holds a dynamic reference to a hash provider. */
class Hash::ProviderRef final
	: public dynamic_reference_nocheck<Hash::Provider>
{
public:
	/** Holds a dynamic reference to a hash algorithm.
	 * @param mod The module that created this reference.
	 * @param algorithm The name of the hash algorithm.
	 */
	ProviderRef(Module* mod, const std::string& algorithm)
		: dynamic_reference_nocheck<Hash::Provider>(mod, "hash/" + algorithm)
	{
	}

	/** Retrieves the name of the referenced hash algorithm. */
	const char* GetAlgorithm() const
	{
		if (GetProvider().empty())
			return nullptr;
		return GetProvider().c_str() + 5;
	}
};

/** Provides a hash context for HMAC generation. */
class Hash::HMACContext final
	: public Hash::Context
{
private:
	/** The data which has been written to this context. */
	std::string buffer;

	/** The underlying hash provider. */
	Hash::ProviderRef provider;

	/** Generates a salt for the HMAC. */
	std::string GenerateSalt()
	{
		if (!provider || provider->IsKDF())
			return {};

		std::vector<char> salt(provider->digest_size);
		ServerInstance->GenRandom(salt.data(), salt.size());
		return std::string(salt.data(), salt.size());
	}

public:
	/** Creates HMAC hash context.
	 * @param prov The underlying hash provider.
	 */
	HMACContext(const Hash::ProviderRef& prov)
		: provider(prov)
	{
	}

	/** @copydoc Hash::HMACContext::Update */
	void Update(const unsigned char *data, size_t len) override
	{
		buffer.append(reinterpret_cast<const char *>(data), len);
	}

	/** @copydoc Hash::HMACContext::Finalize */
	std::string Finalize() override
	{
		if (!provider)
			return {}; // No underlying hash (should never happen).

		auto salt = this->GenerateSalt();
		if (salt.empty())
			return {};

		auto hash = Hash::HMAC(*provider, salt, buffer);
		if (hash.empty())
			return {};

		this->buffer.clear();
		return FMT::format("{}${}", Base64::Encode(salt), Base64::Encode(hash));
	}
};

/** Provides a hash provider for HMAC generation. */
class Hash::HMACProvider final
	: public Hash::Provider
{
private:
	/** The underlying hash provider. */
	Hash::ProviderRef provider;

public:
	/** Creates a provider of HMAC hash contexts.
	 * @param mod The module that created this provider.
	 * @param algorithm The name of the hash algorithm.
	 */
	HMACProvider(Module* mod, const std::string& algorithm)
		: Hash::Provider(mod, FMT::format("hmac-{}", algorithm))
		, provider(mod, algorithm)
	{
	}

	/** @copydoc Hash::Provider::Compare */
	bool Compare(const std::string& hash, const std::string& plain) override
	{
		if (!provider)
			return false; // No underlying hash (should never happen).

		auto sep = hash.find('$');
		if (sep == std::string::npos)
			return false; // Malformed hash.

		auto rawkey = Base64::Decode(hash.substr(0, sep));
		auto rawhash = Base64::Decode(hash.substr(sep + 1));

		auto expected = Hash::HMAC(*provider, rawkey, plain);
		return !expected.empty() && InspIRCd::TimingSafeCompare(rawhash, expected);
	}

	/** @copydoc Hash::Provider::CreateContext */
	std::unique_ptr<Context> CreateContext() override
	{
		return std::make_unique<HMACContext>(provider);
	}

	/** @copydoc Hash::Provider::ToPrintable */
	std::string ToPrintable(const std::string &hash) override
	{
		// We have no way to make this printable without the creating context
		// so we always return the printed form.
		return hash;
	}
};

inline bool Hash::CheckPassword(const std::string& password, const std::string& algorithm, const std::string& value)
{
	auto* hash = ServerInstance->Modules.FindDataService<Hash::Provider>("hash/" + algorithm);
	if (hash)
		return hash->Compare(password, value);

	// The hash algorithm wasn't provided by any modules. If its plain
	// text then we can check it internally.
	if (algorithm.empty() || insp::equalsci(algorithm, "plaintext"))
		return InspIRCd::TimingSafeCompare(password, value);

	ServerInstance->Logs.Debug("HASH", "Unable to check password hashed with an unknown algorithm: {}", algorithm);
	return false;
}

inline std::string Hash::HMAC(Hash::Provider* prov, const std::string& key, const std::string& data)
{
	if (!prov || prov->IsKDF())
		return {};

	auto keybuf = key.length() > prov->block_size ? prov->Hash(key) : key;
	keybuf.resize(prov->block_size);

	std::string hmac1;
	std::string hmac2;
	for (size_t i = 0; i < prov->block_size; ++i)
	{
		hmac1.push_back(static_cast<char>(keybuf[i] ^ 0x5C));
		hmac2.push_back(static_cast<char>(keybuf[i] ^ 0x36));
	}
	hmac2.append(data);
	hmac1.append(prov->Hash(hmac2));

	return prov->Hash(hmac1);
}