md5-lib

A self-contained, high-performance C++17 library for calculating MD5 hashes, adhering strictly to RFC 1321.

This library is designed for production-grade applications, emphasizing performance, security, and ease of use. It is built with modern C++ best practices and is thoroughly tested across all major platforms.

Features

• RFC 1321 Compliant: A faithful and strict implementation of the MD5 standard.
• Streaming Interface: Capable of hashing large files and data streams without loading them entirely into memory.
• High Performance: Optimized for speed by minimizing memory allocations, data copies, and using a high-performance hex formatter.
• Zero Dependencies: Written in pure C++17. Requires only a standard C++ compiler and CMake.
• Cross-Platform: Continuously built and tested on Windows, macOS, and Linux via GitHub Actions.
• Clean & Modern API: Designed with modern C++ best practices, including [[nodiscard]] and a clear, stateless interface.
• Fully Documented: Includes comprehensive API documentation generated by Doxygen and hosted on GitHub Pages.

Requirements

• CMake (version 3.14 or higher)
• A C++17 compliant compiler (e.g., GCC 9+, Clang 7+, MSVC 19.14+)

Building and Testing

The project uses a standard CMake workflow and is self-contained, fetching the Google Test dependency automatically.

# 1. Clone the repository
git clone https://github.com/GregoryKogan/md5-lib.git
cd md5-lib
 
# 2. Configure the project in a 'build' directory
cmake -S . -B build
 
# 3. Build the library and test executable
cmake --build build
 
# 4. Run the tests
cd build
ctest --verbose

Integrating md5-lib

You can integrate md5-lib into your own CMake project in several ways.

Method 1: CMake FetchContent (Recommended)

This is the recommended approach for modern CMake projects. FetchContent will download and configure md5-lib automatically at configure time. It requires no manual cloning.

In your CMakeLists.txt:

cmake_minimum_required(VERSION 3.14)
project(MyApp)
 
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
# --- Add md5-lib ---
include(FetchContent)
FetchContent_Declare(
  md5-lib
  GIT_REPOSITORY https://github.com/GregoryKogan/md5-lib.git
  GIT_TAG        v1.1.0  # Use a specific version tag for stability
)
FetchContent_MakeAvailable(md5-lib)
# --------------------
 
# Define your application's executable
add_executable(my_app main.cpp)
 
# Link against md5-lib
target_link_libraries(my_app PRIVATE md5_lib)

Method 2: Git Submodule and add_subdirectory()

This method is ideal if you need to work offline or want to lock the dependency to a specific commit in your own Git history.

1. Add md5-lib as a submodule to your project:

   # Run this from the root of your repository
   git submodule add https://github.com/GregoryKogan/md5-lib.git third_party/md5-lib

2. In your CMakeLists.txt, add the subdirectory:

   cmake_minimum_required(VERSION 3.14)
   project(MyApp)
    
   set(CMAKE_CXX_STANDARD 17)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)
    
   # --- Add md5-lib ---
   # Assumes the submodule is in third_party/md5-lib
   add_subdirectory(third_party/md5-lib)
   # --------------------
    
   add_executable(my_app main.cpp)
    
   # Link against md5-lib
   target_link_libraries(my_app PRIVATE md5_lib)

Method 3: System-Wide Installation and find_package()

This is a more traditional approach. First, you build and install md5-lib on your system, and then your project finds it using find_package.

1. Build and install md5-lib:

   git clone https://github.com/GregoryKogan/md5-lib.git
   cd md5-lib
   cmake -S . -B build
   cmake --build build
   sudo cmake --install build # May require sudo

2. In your CMakeLists.txt, find and link the installed library:

   cmake_minimum_required(VERSION 3.14)
   project(MyApp)
    
   set(CMAKE_CXX_STANDARD 17)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)
    
   # --- Find and link md5-lib ---
   find_package(md5-lib REQUIRED)
   # ---------------------------
    
   add_executable(my_app main.cpp)
    
   # Note the namespaced target, which is modern CMake best practice
   target_link_libraries(my_app PRIVATE md5_lib::md5_lib)

Simpler Alternative: Manual Copy

For very small projects, you can simply copy the include/md5.h and src/md5.cpp files directly into your source tree and add them to your add_executable or add_library command. This is less maintainable as you won't get updates automatically.

Example Usage

The library exposes its API through the md5.h header and the md5_lib namespace.

#include <iostream>
#include <sstream>
 
#include <md5.h>
 
int main() {
    // Example 1: Hashing from an in-memory string
    const std::string text = "message digest";
    const unsigned char* data = reinterpret_cast<const unsigned char*>(text.data());
    std::string hash_mem = md5_lib::CalculateMD5(data, text.size());
 
    std::cout << "MD5 of \"" << text << "\": " << hash_mem << std::endl;
    // Expected output: MD5 of "message digest": f96b697d7cb7938d525a2f31aaf161d0
 
    // Example 2: Hashing from a std::stringstream
    std::stringstream ss("abcdefghijklmnopqrstuvwxyz");
    std::string hash_stream = md5_lib::CalculateMD5(ss);
 
    std::cout << "MD5 of the alphabet: " << hash_stream << std::endl;
    // Expected output: MD5 of the alphabet: c3fcd3d76192e4007dfb496cca67e13b
 
    return 0;
}

Documentation

For a comprehensive API reference and implementation details, please see the
Doxygen documentation hosted on GitHub Pages.

The documentation is automatically generated and deployed from the main branch.

License

This project is licensed under the MIT License. See the LICENSE file for details.