https://github.com/gregorykogan/md5-lib
A production-grade, high-performance, and self-contained C++17 library for RFC 1321 MD5 hashing, featuring a modern streaming API for large files.
https://github.com/gregorykogan/md5-lib
cmake cpp cpp17 cross-platform hashing library md5 rfc-1321 security self-contained zero-dependencies
Last synced: 19 days ago
JSON representation
A production-grade, high-performance, and self-contained C++17 library for RFC 1321 MD5 hashing, featuring a modern streaming API for large files.
- Host: GitHub
- URL: https://github.com/gregorykogan/md5-lib
- Owner: GregoryKogan
- License: mit
- Created: 2025-09-13T11:56:13.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-09-24T13:47:05.000Z (21 days ago)
- Last Synced: 2025-09-24T15:27:16.006Z (21 days ago)
- Topics: cmake, cpp, cpp17, cross-platform, hashing, library, md5, rfc-1321, security, self-contained, zero-dependencies
- Language: C++
- Homepage: https://gregorykogan.github.io/md5-lib/
- Size: 72.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# md5-lib
[](https://github.com/GregoryKogan/md5-lib/actions/workflows/ci.yml)
[](https://github.com/GregoryKogan/md5-lib/actions/workflows/ci.yml)
[](https://gregorykogan.github.io/md5-lib/)
[](https://opensource.org/licenses/MIT)
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.
```bash
# 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
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:**
```bash
# 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
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`:**
```bash
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
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.
```cpp
#include
#include
#include
int main() {
// Example 1: Hashing from an in-memory string
const std::string text = "message digest";
const unsigned char* data = reinterpret_cast(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](https://GregoryKogan.github.io/md5-lib/)**.
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.