Feature: Blake2xb and LtHash

.github/workflows/code_testing.yml

@@ -62,7 +62,7 @@ jobs:
         uses: dice-group/cpp-conan-release-reusable-workflow/.github/actions/add_conan_provider@main
 
       - name: Configure CMake
-        run: cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=On -DBUILD_EXAMPLES=On -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake -G Ninja -B build .
+        run: cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=On -DWITH_BLAKE=On -DBUILD_EXAMPLES=On -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake -G Ninja -B build .
         env:
           CC: ${{ steps.install_cc.outputs.cc }}
           CXX: ${{ steps.install_cc.outputs.cxx }}
@@ -74,7 +74,7 @@ jobs:
 
       - name: Run tests
         working-directory: build
-        run: ctest --verbose -j2
+        run: ctest --verbose -j2 -E ".*Benchmark.*"
 
       - name: Run examples
         working-directory: build

.github/workflows/detect-pobr-diff.yml

@@ -16,8 +16,8 @@ jobs:
       conan-version: 2.3.1
       base-branch: ${{ github.base_ref }}
       search-path: >
-        include/dice/hash/internal
-      abi-version-header: include/dice/hash/version.hpp
+        src/dice/hash/internal
+      abi-version-header: src/dice/hash/version.hpp
       abi-version-const: dice::hash::pobr_version
     secrets:
       CONAN_USER: ""

.github/workflows/publish-release.yml

@@ -17,7 +17,7 @@ jobs:
     with:
       public_artifactory: true
       os: ubuntu-22.04
-      compiler: clang-14
+      compiler: clang-17
       cmake-version: 3.24.0
       conan-version: 2.3.0
     secrets:

.gitignore

@@ -163,4 +163,5 @@ modules.xml
 
 test_package/build
 conan_provider.cmake
-include/dice/hash/version.hpp
+/src/dice/hash/version.hpp
+/src/dice/hash/blake/internal/blake3/libblake3.pc

CMakeLists.txt

@@ -7,6 +7,9 @@ project(
         HOMEPAGE_URL "https://dice-group.github.io/dice-hash/")
 set(POBR_VERSION 1)  # Persisted Object Binary Representation Version
 
+include(cmake/boilerplate_init.cmake)
+boilerplate_init()
+
 # set gcc-10 and clang-10 as minimum versions see
 # https://stackoverflow.com/questions/14933172/how-can-i-add-a-minimum-compiler-version-requisite#14934542
 set(MIN_COMPILER_VERSION_GCC "10.0.0")
@@ -25,23 +28,61 @@ else()
     MESSAGE(WARNING "Could not verify that your compiler (${CMAKE_CXX_COMPILER}) supports all needed features.")
 endif()
 
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/version.hpp.in ${CMAKE_CURRENT_SOURCE_DIR}/include/dice/hash/version.hpp)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/version.hpp.in ${CMAKE_CURRENT_SOURCE_DIR}/src/dice/hash/version.hpp)
+
+OPTION(WITH_BLAKE "Enable usage of the external library sodium for Blake2b, Blake2Xb and LtHash support" OFF)
 
 if (PROJECT_IS_TOP_LEVEL)
     if (BUILD_TESTING)
         set(CONAN_INSTALL_ARGS "${CONAN_INSTALL_ARGS};-o=&:with_test_deps=True")
     endif ()
+    if (WITH_BLAKE)
+        set(CONAN_INSTALL_ARGS "${CONAN_INSTALL_ARGS};-o=&:with_blake=True")
+    endif ()
 endif ()
 
-add_library(${PROJECT_NAME} INTERFACE)
+if (WITH_BLAKE)
+    find_package(sodium QUIET) # try canonical name first
+    set(sodium_dep "sodium")
+    if (NOT sodium_FOUND)
+        find_package(libsodium QUIET) #  next try the name used by conan
+        set(sodium_dep "libsodium::libsodium")
+        if (NOT libsodium_FOUND)
+            include(cmake/FindSodium.cmake) # finally try the FindSodium.cmake provided with this repo
+            set(sodium_dep "sodium")
+            if (NOT Sodium_FOUND)
+                message(FATAL_ERROR "Sodium was not found.")
+            endif ()
+        endif ()
+    endif ()
+
+    find_package(highway REQUIRED)
+endif ()
+
+add_subdirectory(src/dice/hash/blake/internal/blake3)
+
+add_library(${PROJECT_NAME}
+        src/dice/hash/lthash/MathEngine_Hwy.cpp
+)
 add_library(${PROJECT_NAME}::${PROJECT_NAME} ALIAS ${PROJECT_NAME})
 
+target_link_libraries(${PROJECT_NAME}
+        INTERFACE blake3
+)
+
 target_include_directories(
         ${PROJECT_NAME}
-        INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>)
+        PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>)
+
+if (WITH_BLAKE)
+    target_link_libraries(${PROJECT_NAME}
+            INTERFACE ${sodium_dep}
+            PRIVATE highway::highway
+    )
+endif ()
 
-include(cmake/install_interface_library.cmake)
-install_interface_library(${PROJECT_NAME} "include")
+include(cmake/install_library.cmake)
+install_cpp_library(${PROJECT_NAME} "src")
 
 if(PROJECT_IS_TOP_LEVEL AND BUILD_TESTING)
     include(CTest)

README.md

@@ -7,17 +7,19 @@ dice-hash provides a framework to generate stable hashes. It provides state-of-t
 - [wyhash](https://github.com/wangyi-fudan/wyhash)
 - "martinus", the internal hash function from [robin-hood-hashing](https://github.com/martinus/robin-hood-hashing)
 
+These three, additional, general purpose hash functions are also (optionally) provided
+- [Blake2b](https://www.blake2.net)
+- [Blake2Xb](https://www.blake2.net/blake2x.pdf)
+- [LtHash](https://engineering.fb.com/2019/03/01/security/homomorphic-hashing)
+
 **📦 STL out of the box:** dice-hash supports many common STL types already: 
 arithmetic types like `bool`, `int`, `double`, ... etc.; collections like `std::unordered_map/set`, `std::map/set`, `std::vector`, `std::tuple`, `std::pair`, `std::optional`, `std::variant`, `std::array` and; all combinations of them. 
 
-**🔩 extensible:** dice-hash supports you with helper functions to define hashes for your own classes. Checkout [usage](#usage). 
-
-
-
+**🔩 extensible:** dice-hash supports you with helper functions to define hashes for your own classes. Checkout [usage](#usage).
 
 ## Requirements
-
-A C++20 compatible compiler. Code was only tested on x86_64.
+- A C++20 compatible compiler. Code was only tested on x86_64.
+- If you want to use [Blake2b](https://www.blake2.net), [Blake2Xb](https://www.blake2.net/blake2x.pdf) or [LtHash](https://engineering.fb.com/2019/03/01/security/homomorphic-hashing): [libsodium](https://doc.libsodium.org/) (either using conan or a local system installation) (for more details scroll down to "Usage for general data hashing")
 
 ## Include it into your projects 
 
@@ -55,13 +57,14 @@ make -j tests_dice_hash
 Note: This example uses conan as dependency provider, other providers are possible.
 See https://cmake.org/cmake/help/latest/guide/using-dependencies/index.html#dependency-providers
 
-## usage
+## Usage for C++ container hashing
 You need to include a single header:
 ```c++
 #include <dice/hash.hpp>
 ```
 
 The hash is already defined for a lot of common types. In that case you can use the `DiceHash` just like `std::hash`.
+This means these hashes return `size_t`, if you need larger hashes skip to the section below.
 ```c++
 dice::hash::DiceHash<int> hash;
 hash(42);
@@ -104,3 +107,44 @@ One simple example can be found [here](examples/customContainer.cpp).
 
 If you want to use `DiceHash` in a different structure (like `std::unordered_map`), you will need to set `DiceHash` as the correct template parameter.
 [This](examples/usageForUnorderedSet.cpp) is one example.
+
+## Usage for general data hashing
+**The hash functions mentioned in this section are enabled/disabled using the feature flag `WITH_SODIUM=ON/OFF`.**
+**Enabling this flag (default behaviour) results in [libsodium](https://doc.libsodium.org/) being required as a dependency.**
+**If using conan, [libsodium](https://doc.libsodium.org/) will be fetched using conan, otherwise dice-hash will look for a local system installation.**
+
+The hashes mentioned here are not meant to be used in C++ containers as they do _not_ return `size_t`.
+They are instead meant as general hashing functions for arbitrary data.
+
+### [Blake2b](https://www.blake2.net/) - ["fast secure hashing"](https://www.blake2.net/) (with output sizes from 16 bytes up to 64 bytes)
+["BLAKE2 is a cryptographic hash function faster than MD5, SHA-1, SHA-2, and SHA-3, yet is at least as secure as the latest standard SHA-3."](https://www.blake2.net/)
+
+To use it you need to include
+```c++
+#include <dice/hash/blake2/Blake2b.hpp>
+```
+For a usage examples see: [examples/blake2b.cpp](examples/blake2b.cpp).
+
+### [Blake2Xb](https://www.blake2.net/blake2x.pdf) - arbitrary length hashing based on [Blake2b](https://www.blake2.net/)
+Blake2Xb is a hash function that produces hashes of arbitrary length.
+
+To use it you need to include
+```c++
+#include <dice/hash/blake2/Blake2xb.hpp>
+```
+For a usage examples see: [examples/blake2xb.cpp](examples/blake2xb.cpp).
+
+### [LtHash](https://engineering.fb.com/2019/03/01/security/homomorphic-hashing/) - homomorphic/multiset hashing
+LtHash is a multiset/homomorphic hash function, meaning, instead of working on streams of data, it digests
+individual "objects". This means you can add and remove "objects" to/from an `LtHash` (object by object)
+as if it were a multiset and then read the hash that would result from hashing that multiset.
+
+Small non-code example that shows the basic principle:
+> LtHash({apple}) + LtHash({banana}) - LtHash({peach}) + LtHash({banana}) = LtHash({apple<sup>1</sup>, banana<sup>2</sup>, peach<sup>-1</sup>})
+
+To use it you need to include
+```c++
+#include <dice/hash/lthash/LtHash.hpp>
+// automatically includes <dice/hash/blake/Blake3.hpp>
+```
+For a usage example see [examples/ltHash.cpp](examples/ltHash.cpp).