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

# 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

# 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

Single responsibility: Library handles hashing only, utility handles CLI
Directory hashing: Recursively hashes all files in sorted order for deterministic results
Static linking: Utility is statically linked for portability (-static flag in Makefile)
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

2.7 KiB Raw Blame History