79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
dshash is a simple SHA256 hashing library and command-line utility with no external dependencies. It consists of:
|
|
- **Library** (`src/`): Pure C++ SHA256 implementation that can hash strings, files, and directory trees
|
|
- **Utility** (`dshash/`): Command-line tool for hashing files and directories
|
|
- **Tests** (`tests/`): Comprehensive test suite including NIST vectors and system comparisons
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Build the utility (from project root)
|
|
cd dshash && make clean && make
|
|
|
|
# Alternative: Use the build script
|
|
./build.sh # Creates output/dshash
|
|
|
|
# Build just the library for testing
|
|
cd tests
|
|
g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src
|
|
```
|
|
|
|
## Test Commands
|
|
|
|
```bash
|
|
# Run all tests (recommended)
|
|
./test.sh # or ./tests/test.sh
|
|
|
|
# The test suite includes:
|
|
# - Library unit tests
|
|
# - Utility tests
|
|
# - System sha256sum comparisons
|
|
# - NIST test vectors
|
|
# - Stress tests
|
|
# - Edge cases
|
|
# - Performance benchmarks
|
|
|
|
# Build and run a specific test
|
|
cd tests
|
|
g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src && ./test_lib
|
|
g++ -std=c++17 -O2 -o test_stress test_stress.cpp ../src/dshash.cpp -I../src && ./test_stress
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### SHA256 Implementation
|
|
The DSHash class (`src/dshash.hpp`) implements SHA256 from scratch:
|
|
- Uses standard SHA256 constants and operations (Ch, Maj, Σ0, Σ1, etc.)
|
|
- Processes data in 64-byte blocks
|
|
- Returns hash as `std::array<uint8_t, 32>` or hex string
|
|
- No external crypto library dependencies
|
|
|
|
### Key Design Decisions
|
|
1. **Single responsibility**: Library handles hashing only, utility handles CLI
|
|
2. **Directory hashing**: Recursively hashes all files in sorted order for deterministic results
|
|
3. **Static linking**: Utility is statically linked for portability (`-static` flag in Makefile)
|
|
4. **C++17**: Uses `std::filesystem` for cross-platform file operations
|
|
|
|
### Testing Strategy
|
|
The test suite (`tests/test.sh`) validates correctness by:
|
|
- Comparing output with system `sha256sum` for various inputs
|
|
- Verifying against official NIST test vectors
|
|
- Testing edge cases (empty files, special characters, padding boundaries)
|
|
- Stress testing with large files and many operations
|
|
|
|
## Development Guidelines
|
|
|
|
When modifying the SHA256 implementation:
|
|
- Ensure all NIST test vectors still pass
|
|
- Verify against system sha256sum for any new test cases
|
|
- The implementation follows FIPS 180-4 specification
|
|
|
|
When adding features to the utility:
|
|
- Maintain backward compatibility with existing command-line interface
|
|
- Keep the utility simple and focused on hashing
|
|
- Preserve static linking for distribution |