File Hashing

The file hashing module provides utilities for generating various types of file hashes and checksums for data integrity verification.

Module Overview

Hash Management Functions - Fixed Version Provides standardized hash functions that actually exist and work properly

siege_utilities.files.hashing.calculate_file_hash(file_path)[source]

Alias for get_file_hash with SHA256 - for backward compatibility.

Return type:

str

siege_utilities.files.hashing.generate_sha256_hash_for_file(file_path)[source]

Generate SHA256 hash for a file - chunked reading for large files.

Deprecated since version 3.19.0: Use calculate_file_hash() or get_file_hash() instead. Will be removed in v4.0.0.

SECURITY: This function validates paths to prevent path traversal attacks and access to sensitive system files.

Parameters:

file_path – Path to the file (str or Path object)

Returns:

SHA256 hash as hexadecimal string

Raises:
Return type:

str

Example

>>> hash_val = generate_sha256_hash_for_file("data.txt")
siege_utilities.files.hashing.get_file_hash(file_path, algorithm='sha256')[source]

Generate hash for a file using specified algorithm.

SECURITY: This function validates paths to prevent path traversal attacks and access to sensitive system files.

Parameters:

  • file_path – Path to the file (str or Path object)

  • algorithm – Hash algorithm to use (‘sha256’, ‘md5’, ‘sha1’, etc.)

Returns:

Hash as hexadecimal string

Raises:
Return type:

str

Example

>>> hash_val = get_file_hash("data.txt", "sha256")
siege_utilities.files.hashing.get_quick_file_signature(file_path)[source]

Generate a quick file signature using file stats + partial hash Faster for change detection, not cryptographically secure

SECURITY: This function validates paths to prevent path traversal attacks and access to sensitive system files.

Parameters:

file_path – Path to the file

Returns:

Quick signature string (‘missing’, fallback stat string, or hash)

Raises:

  • PathSecurityError – If path fails security validation

  • Exception – If both primary and fallback signature generation fail (logged before re-raise)

Return type:

str

Example

>>> sig = get_quick_file_signature("data.txt")
>>> get_quick_file_signature("/etc/passwd")
Security Changes:

  • Now validates paths to block path traversal

  • Blocks access to sensitive system files

siege_utilities.files.hashing.verify_file_integrity(file_path, expected_hash, algorithm='sha256')[source]

Verify file integrity by comparing with expected hash.

SECURITY: This function validates paths to prevent path traversal attacks and access to sensitive system files (through get_file_hash).

Parameters:

  • file_path – Path to the file

  • expected_hash – Expected hash value

  • algorithm – Hash algorithm used

Returns:

True if file matches expected hash, False if hash does not match

Raises:
Return type:

bool

Example

>>> expected = "abc123..."
>>> if verify_file_integrity("data.txt", expected):
...     print("File integrity verified")

Functions

siege_utilities.files.hashing.calculate_file_hash(file_path)[source]

Alias for get_file_hash with SHA256 - for backward compatibility.

Return type:

str

siege_utilities.files.hashing.verify_file_integrity(file_path, expected_hash, algorithm='sha256')[source]

Verify file integrity by comparing with expected hash.

SECURITY: This function validates paths to prevent path traversal attacks and access to sensitive system files (through get_file_hash).

Parameters:

  • file_path – Path to the file

  • expected_hash – Expected hash value

  • algorithm – Hash algorithm used

Returns:

True if file matches expected hash, False if hash does not match

Raises:
Return type:

bool

Example

>>> expected = "abc123..."
>>> if verify_file_integrity("data.txt", expected):
...     print("File integrity verified")

Usage Examples

Basic file hashing:

import siege_utilities

# Calculate MD5 hash
md5_hash = siege_utilities.calculate_md5('document.pdf')
print(f"MD5: {md5_hash}")

# Calculate SHA256 hash
sha256_hash = siege_utilities.calculate_sha256('document.pdf')
print(f"SHA256: {sha256_hash}")

# Calculate SHA1 hash
sha1_hash = siege_utilities.calculate_sha1('document.pdf')
print(f"SHA1: {sha1_hash}")

Generic hashing with algorithm selection:

# Use generic hash function
hash_value = siege_utilities.calculate_file_hash('data.csv', algorithm='sha256')
print(f"Hash: {hash_value}")

# Available algorithms: md5, sha1, sha256, sha512
algorithms = ['md5', 'sha1', 'sha256']
hashes = {}

for algo in algorithms:
    hashes[algo] = siege_utilities.calculate_file_hash('large_file.dat', algorithm=algo)

for algo, hash_val in hashes.items():
    print(f"{algo.upper()}: {hash_val}")

File integrity verification:

Batch processing:

Unit Tests

The file hashing module has comprehensive test coverage:

Test Results: All file hashing tests pass successfully with comprehensive coverage.