provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/crypto/checksums.py

@@ -0,0 +1,301 @@
+"""Checksum verification and management."""
+
+from pathlib import Path
+
+from provide.foundation.crypto.algorithms import DEFAULT_ALGORITHM
+from provide.foundation.crypto.hashing import hash_data, hash_file
+from provide.foundation.crypto.utils import compare_hash
+from provide.foundation.errors.resources import ResourceError
+from provide.foundation.logger import get_logger
+
+plog = get_logger(__name__)
+
+
+def verify_file(
+    path: Path | str,
+    expected_hash: str,
+    algorithm: str = DEFAULT_ALGORITHM,
+) -> bool:
+    """Verify a file matches an expected hash.
+
+    Args:
+        path: File path
+        expected_hash: Expected hash value
+        algorithm: Hash algorithm
+
+    Returns:
+        True if hash matches, False otherwise
+
+    Raises:
+        ResourceError: If file cannot be read
+        ValidationError: If algorithm is not supported
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    try:
+        actual_hash = hash_file(path, algorithm)
+        matches = compare_hash(actual_hash, expected_hash)
+
+        if matches:
+            plog.debug(
+                "✅ Checksum verified",
+                path=str(path),
+                algorithm=algorithm,
+            )
+        else:
+            plog.warning(
+                "❌ Checksum mismatch",
+                path=str(path),
+                algorithm=algorithm,
+                expected=expected_hash[:16] + "...",
+                actual=actual_hash[:16] + "...",
+            )
+
+        return matches
+
+    except ResourceError:
+        plog.error(
+            "❌ Failed to verify checksum - file not found",
+            path=str(path),
+        )
+        return False
+
+
+def verify_data(
+    data: bytes,
+    expected_hash: str,
+    algorithm: str = DEFAULT_ALGORITHM,
+) -> bool:
+    """Verify data matches an expected hash.
+
+    Args:
+        data: Data to verify
+        expected_hash: Expected hash value
+        algorithm: Hash algorithm
+
+    Returns:
+        True if hash matches, False otherwise
+
+    Raises:
+        ValidationError: If algorithm is not supported
+    """
+    actual_hash = hash_data(data, algorithm)
+    matches = compare_hash(actual_hash, expected_hash)
+
+    if matches:
+        plog.debug(
+            "✅ Data checksum verified",
+            algorithm=algorithm,
+            size=len(data),
+        )
+    else:
+        plog.warning(
+            "❌ Data checksum mismatch",
+            algorithm=algorithm,
+            expected=expected_hash[:16] + "...",
+            actual=actual_hash[:16] + "...",
+        )
+
+    return matches
+
+
+def calculate_checksums(
+    path: Path | str,
+    algorithms: list[str] | None = None,
+) -> dict[str, str]:
+    """Calculate multiple checksums for a file.
+
+    Args:
+        path: File path
+        algorithms: List of algorithms (defaults to sha256 and md5)
+
+    Returns:
+        Dictionary mapping algorithm name to hex digest
+
+    Raises:
+        ResourceError: If file cannot be read
+        ValidationError: If any algorithm is not supported
+    """
+    if algorithms is None:
+        algorithms = ["sha256", "md5"]
+
+    from provide.foundation.crypto.hashing import hash_file_multiple
+
+    checksums = hash_file_multiple(path, algorithms)
+
+    plog.debug(
+        "📝 Calculated checksums",
+        path=str(path),
+        algorithms=algorithms,
+    )
+
+    return checksums
+
+
+def parse_checksum_file(
+    path: Path | str,
+    algorithm: str | None = None,
+) -> dict[str, str]:
+    """Parse a checksum file and return filename to hash mapping.
+
+    Supports common checksum file formats:
+    - SHA256: "hash  filename" or "hash filename"
+    - MD5: "hash  filename" or "hash filename"
+    - SHA256SUMS: "hash  filename"
+    - MD5SUMS: "hash  filename"
+
+    Args:
+        path: Path to checksum file
+        algorithm: Expected algorithm (for validation)
+
+    Returns:
+        Dictionary mapping filename to hash
+
+    Raises:
+        ResourceError: If file cannot be read
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.exists():
+        raise ResourceError(
+            f"Checksum file not found: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        )
+
+    checksums = {}
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+
+                # Split on whitespace (handle both single and double space)
+                parts = line.split(None, 1)
+                if len(parts) == 2:
+                    hash_value, filename = parts
+                    # Remove any leading asterisk (binary mode indicator)
+                    if filename.startswith("*"):
+                        filename = filename[1:]
+                    checksums[filename] = hash_value.lower()
+
+        plog.debug(
+            "📄 Parsed checksum file",
+            path=str(path),
+            entries=len(checksums),
+            algorithm=algorithm,
+        )
+
+        return checksums
+
+    except OSError as e:
+        raise ResourceError(
+            f"Failed to read checksum file: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        ) from e
+
+
+def write_checksum_file(
+    checksums: dict[str, str],
+    path: Path | str,
+    algorithm: str = DEFAULT_ALGORITHM,
+    binary_mode: bool = True,
+) -> None:
+    """Write checksums to a file in standard format.
+
+    Args:
+        checksums: Dictionary mapping filename to hash
+        path: Path to write checksum file
+        algorithm: Algorithm name (for comments)
+        binary_mode: Whether to use binary mode indicator (*)
+
+    Raises:
+        ResourceError: If file cannot be written
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            # Write header comment
+            f.write(f"# {algorithm.upper()} checksums\n")
+            f.write("# Generated by provide.foundation\n\n")
+
+            # Write checksums
+            for filename, hash_value in sorted(checksums.items()):
+                if binary_mode:
+                    f.write(f"{hash_value}  *{filename}\n")
+                else:
+                    f.write(f"{hash_value}  {filename}\n")
+
+        plog.debug(
+            "📝 Wrote checksum file",
+            path=str(path),
+            entries=len(checksums),
+            algorithm=algorithm,
+        )
+
+    except OSError as e:
+        raise ResourceError(
+            f"Failed to write checksum file: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        ) from e
+
+
+def verify_checksum_file(
+    checksum_file: Path | str,
+    base_dir: Path | str | None = None,
+    algorithm: str = DEFAULT_ALGORITHM,
+    stop_on_error: bool = False,
+) -> tuple[list[str], list[str]]:
+    """Verify all files listed in a checksum file.
+
+    Args:
+        checksum_file: Path to checksum file
+        base_dir: Base directory for relative paths (defaults to checksum file dir)
+        algorithm: Hash algorithm to use
+        stop_on_error: Whether to stop on first verification failure
+
+    Returns:
+        Tuple of (verified_files, failed_files)
+
+    Raises:
+        ResourceError: If checksum file cannot be read
+    """
+    if isinstance(checksum_file, str):
+        checksum_file = Path(checksum_file)
+
+    if base_dir is None:
+        base_dir = checksum_file.parent
+    elif isinstance(base_dir, str):
+        base_dir = Path(base_dir)
+
+    checksums = parse_checksum_file(checksum_file, algorithm)
+
+    verified = []
+    failed = []
+
+    for filename, expected_hash in checksums.items():
+        file_path = base_dir / filename
+
+        if verify_file(file_path, expected_hash, algorithm):
+            verified.append(filename)
+        else:
+            failed.append(filename)
+            if stop_on_error:
+                break
+
+    plog.info(
+        "📊 Checksum verification complete",
+        verified=len(verified),
+        failed=len(failed),
+        total=len(checksums),
+    )
+
+    return verified, failed

provide/foundation/crypto/constants.py

@@ -0,0 +1,57 @@
+"""Cryptographic constants and configuration."""
+
+from typing import Final
+
+# Ed25519 constants
+ED25519_PRIVATE_KEY_SIZE: Final[int] = 32
+ED25519_PUBLIC_KEY_SIZE: Final[int] = 32
+ED25519_SIGNATURE_SIZE: Final[int] = 64
+
+# RSA key sizes
+DEFAULT_RSA_KEY_SIZE: Final[int] = 2048
+SUPPORTED_RSA_SIZES: Final[set[int]] = {2048, 3072, 4096}
+
+# ECDSA curves
+DEFAULT_ECDSA_CURVE: Final[str] = "secp384r1"
+SUPPORTED_EC_CURVES: Final[set[str]] = {
+    "secp256r1",
+    "secp384r1",
+    "secp521r1",
+}
+
+# Key types
+SUPPORTED_KEY_TYPES: Final[set[str]] = {"rsa", "ecdsa", "ed25519"}
+
+# Default algorithms for different use cases
+DEFAULT_SIGNATURE_ALGORITHM: Final[str] = "ed25519"  # Modern default for new code
+DEFAULT_CERTIFICATE_KEY_TYPE: Final[str] = "ecdsa"  # Good balance for TLS/PKI
+DEFAULT_CERTIFICATE_CURVE: Final[str] = DEFAULT_ECDSA_CURVE
+
+# Certificate defaults
+DEFAULT_CERTIFICATE_VALIDITY_DAYS: Final[int] = 365
+MIN_CERTIFICATE_VALIDITY_DAYS: Final[int] = 1
+MAX_CERTIFICATE_VALIDITY_DAYS: Final[int] = 3650  # 10 years
+
+
+# Optional config integration
+def _get_config_value(key: str, default: str | int) -> str | int:
+    """Get crypto config value with fallback to default."""
+    try:
+        from provide.foundation.config import get_config
+
+        return get_config(f"crypto.{key}", default)
+    except ImportError:
+        # Config system not available, use defaults
+        return default
+
+
+def get_default_hash_algorithm() -> str:
+    """Get default hash algorithm from config or fallback."""
+    from provide.foundation.crypto.algorithms import DEFAULT_ALGORITHM
+
+    return str(_get_config_value("hash_algorithm", DEFAULT_ALGORITHM))
+
+
+def get_default_signature_algorithm() -> str:
+    """Get default signature algorithm from config or fallback."""
+    return str(_get_config_value("signature_algorithm", DEFAULT_SIGNATURE_ALGORITHM))

provide/foundation/crypto/hashing.py

@@ -0,0 +1,265 @@
+"""Core hashing operations."""
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import BinaryIO
+
+from provide.foundation.crypto.algorithms import (
+    DEFAULT_ALGORITHM,
+    get_hasher,
+    validate_algorithm,
+)
+from provide.foundation.errors.resources import ResourceError
+from provide.foundation.logger import get_logger
+
+plog = get_logger(__name__)
+
+# Default chunk size for file reading (8KB)
+DEFAULT_CHUNK_SIZE = 8192
+
+
+def hash_file(
+    path: Path | str,
+    algorithm: str = DEFAULT_ALGORITHM,
+    chunk_size: int = DEFAULT_CHUNK_SIZE,
+) -> str:
+    """Hash a file's contents.
+
+    Args:
+        path: File path
+        algorithm: Hash algorithm (sha256, sha512, md5, etc.)
+        chunk_size: Size of chunks to read at a time
+
+    Returns:
+        Hex digest of file hash
+
+    Raises:
+        ResourceError: If file cannot be read
+        ValidationError: If algorithm is not supported
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.exists():
+        raise ResourceError(
+            f"File not found: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        )
+
+    if not path.is_file():
+        raise ResourceError(
+            f"Path is not a file: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        )
+
+    validate_algorithm(algorithm)
+    hasher = get_hasher(algorithm)
+
+    try:
+        with open(path, "rb") as f:
+            while chunk := f.read(chunk_size):
+                hasher.update(chunk)
+
+        hash_value = hasher.hexdigest()
+        plog.debug(
+            "🔐 Hashed file",
+            path=str(path),
+            algorithm=algorithm,
+            hash=hash_value[:16] + "...",
+        )
+        return hash_value
+
+    except OSError as e:
+        raise ResourceError(
+            f"Failed to read file: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        ) from e
+
+
+def hash_data(
+    data: bytes,
+    algorithm: str = DEFAULT_ALGORITHM,
+) -> str:
+    """Hash binary data.
+
+    Args:
+        data: Data to hash
+        algorithm: Hash algorithm
+
+    Returns:
+        Hex digest
+
+    Raises:
+        ValidationError: If algorithm is not supported
+    """
+    validate_algorithm(algorithm)
+    hasher = get_hasher(algorithm)
+    hasher.update(data)
+
+    hash_value = hasher.hexdigest()
+    plog.debug(
+        "🔐 Hashed data",
+        algorithm=algorithm,
+        size=len(data),
+        hash=hash_value[:16] + "...",
+    )
+    return hash_value
+
+
+def hash_string(
+    text: str,
+    algorithm: str = DEFAULT_ALGORITHM,
+    encoding: str = "utf-8",
+) -> str:
+    """Hash a text string.
+
+    Args:
+        text: Text to hash
+        algorithm: Hash algorithm
+        encoding: Text encoding
+
+    Returns:
+        Hex digest
+
+    Raises:
+        ValidationError: If algorithm is not supported
+    """
+    return hash_data(text.encode(encoding), algorithm)
+
+
+def hash_stream(
+    stream: BinaryIO,
+    algorithm: str = DEFAULT_ALGORITHM,
+    chunk_size: int = DEFAULT_CHUNK_SIZE,
+) -> str:
+    """Hash data from a stream.
+
+    Args:
+        stream: Binary stream to read from
+        algorithm: Hash algorithm
+        chunk_size: Size of chunks to read at a time
+
+    Returns:
+        Hex digest
+
+    Raises:
+        ValidationError: If algorithm is not supported
+    """
+    validate_algorithm(algorithm)
+    hasher = get_hasher(algorithm)
+
+    bytes_read = 0
+    while chunk := stream.read(chunk_size):
+        hasher.update(chunk)
+        bytes_read += len(chunk)
+
+    hash_value = hasher.hexdigest()
+    plog.debug(
+        "🔐 Hashed stream",
+        algorithm=algorithm,
+        bytes_read=bytes_read,
+        hash=hash_value[:16] + "...",
+    )
+    return hash_value
+
+
+def hash_file_multiple(
+    path: Path | str,
+    algorithms: list[str],
+    chunk_size: int = DEFAULT_CHUNK_SIZE,
+) -> dict[str, str]:
+    """Hash a file with multiple algorithms in a single pass.
+
+    This is more efficient than calling hash_file multiple times.
+
+    Args:
+        path: File path
+        algorithms: List of hash algorithms
+        chunk_size: Size of chunks to read at a time
+
+    Returns:
+        Dictionary mapping algorithm name to hex digest
+
+    Raises:
+        ResourceError: If file cannot be read
+        ValidationError: If any algorithm is not supported
+    """
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.exists():
+        raise ResourceError(
+            f"File not found: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        )
+
+    # Create hashers for all algorithms
+    hashers = {}
+    for algo in algorithms:
+        validate_algorithm(algo)
+        hashers[algo] = get_hasher(algo)
+
+    # Read file once and update all hashers
+    try:
+        with open(path, "rb") as f:
+            while chunk := f.read(chunk_size):
+                for hasher in hashers.values():
+                    hasher.update(chunk)
+
+        # Get results
+        results = {algo: hasher.hexdigest() for algo, hasher in hashers.items()}
+
+        plog.debug(
+            "🔐 Hashed file with multiple algorithms",
+            path=str(path),
+            algorithms=algorithms,
+        )
+
+        return results
+
+    except OSError as e:
+        raise ResourceError(
+            f"Failed to read file: {path}",
+            resource_type="file",
+            resource_path=str(path),
+        ) from e
+
+
+def hash_chunks(
+    chunks: Iterator[bytes],
+    algorithm: str = DEFAULT_ALGORITHM,
+) -> str:
+    """Hash an iterator of byte chunks.
+
+    Useful for hashing data that comes in chunks, like from a network stream.
+
+    Args:
+        chunks: Iterator yielding byte chunks
+        algorithm: Hash algorithm
+
+    Returns:
+        Hex digest
+
+    Raises:
+        ValidationError: If algorithm is not supported
+    """
+    validate_algorithm(algorithm)
+    hasher = get_hasher(algorithm)
+
+    bytes_processed = 0
+    for chunk in chunks:
+        hasher.update(chunk)
+        bytes_processed += len(chunk)
+
+    hash_value = hasher.hexdigest()
+    plog.debug(
+        "🔐 Hashed chunks",
+        algorithm=algorithm,
+        bytes_processed=bytes_processed,
+        hash=hash_value[:16] + "...",
+    )
+    return hash_value