pqblocks-files 0.1.0__py3-none-any.whl

pqblocks_files/ae.py

@@ -0,0 +1,92 @@
+"""AEAD layer: ChaCha20-Poly1305 and the HKDF key derivations for the pfsh v1 body and header.
+
+Contract:
+  derive_payload_key(file_key: bytes, chunk_nonce: bytes) -> 32B
+  derive_header_mac_key(file_key: bytes) -> 32B
+  chacha20poly1305_encrypt(key, nonce, pt, aad=b'') -> ciphertext || tag
+  chacha20poly1305_decrypt(key, nonce, ct_tag, aad=b'') -> plaintext
+
+Primitives come from pyca/cryptography (audited library).
+HKDF-SHA256 via the same library. No hand-rolled crypto.
+"""
+
+from __future__ import annotations
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from pqblocks_files.pqtypes import TagVerificationFailed
+
+
+def derive_payload_key(file_key: bytes, chunk_nonce: bytes) -> bytes:
+    """HKDF-SHA256(ikm=file_key, salt=chunk_nonce, info='payload') -> 32B."""
+    if len(file_key) != 16:
+        raise ValueError(f"file_key must be 16 bytes, got {len(file_key)}")
+    if len(chunk_nonce) != 12:
+        raise ValueError(f"chunk_nonce must be 12 bytes, got {len(chunk_nonce)}")
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=chunk_nonce,
+        info=b"payload",
+    )
+    return hkdf.derive(file_key)
+
+
+def derive_header_mac_key(file_key: bytes) -> bytes:
+    """HKDF-SHA256(ikm=file_key, salt=b'', info='header') -> 32B."""
+    if len(file_key) != 16:
+        raise ValueError(f"file_key must be 16 bytes, got {len(file_key)}")
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=b"",
+        info=b"header",
+    )
+    return hkdf.derive(file_key)
+
+
+def chacha20poly1305_encrypt(
+    key: bytes,
+    nonce: bytes,
+    pt: bytes,
+    aad: bytes = b"",
+) -> bytes:
+    """Encrypt pt with ChaCha20-Poly1305. Returns ciphertext || tag.
+
+    key: 32 bytes, nonce: 12 bytes. Output length = len(pt) + 16.
+    """
+    if len(key) != 32:
+        raise ValueError(f"key must be 32 bytes, got {len(key)}")
+    if len(nonce) != 12:
+        raise ValueError(f"nonce must be 12 bytes, got {len(nonce)}")
+    aead = ChaCha20Poly1305(key)
+    return aead.encrypt(nonce, pt, aad)
+
+
+def chacha20poly1305_decrypt(
+    key: bytes,
+    nonce: bytes,
+    ct_tag: bytes,
+    aad: bytes = b"",
+) -> bytes:
+    """Decrypt ct_tag with ChaCha20-Poly1305. Returns plaintext.
+
+    Raises TagVerificationFailed if the Poly1305 tag does not verify.
+    key: 32 bytes, nonce: 12 bytes.
+    """
+    if len(key) != 32:
+        raise ValueError(f"key must be 32 bytes, got {len(key)}")
+    if len(nonce) != 12:
+        raise ValueError(f"nonce must be 12 bytes, got {len(nonce)}")
+    if len(ct_tag) < 16:
+        raise TagVerificationFailed(
+            f"ct_tag too short: {len(ct_tag)} bytes (minimum 16 for tag)"
+        )
+    aead = ChaCha20Poly1305(key)
+    try:
+        return aead.decrypt(nonce, ct_tag, aad)
+    except InvalidTag:
+        raise TagVerificationFailed("Poly1305 tag verification failed") from None

pqblocks_files/chunker.py

@@ -0,0 +1,125 @@
+"""Chunker for the pfsh v1 body.
+
+Contract:
+  _chunk(plaintext: bytes, file_key: bytes (16B)) -> list[(nonce: bytes (12B), chunk: bytes)]
+  _unchunk(chunked: list[(nonce: bytes (12B), chunk: bytes)], file_key: bytes) -> bytes   (private: test helper)
+
+Where chunk = ciphertext || tag (16B Poly1305 tag)
+- Chunks are 64 KiB max ciphertext
+- Nonce structure (12 bytes):
+  - Bytes 0-7: big-endian 64-bit chunk counter (starting at 0)
+  - Byte 8: 0x00 (non-final) or 0x01 (final chunk)
+  - Bytes 9-11: reserved, MUST be 0x00
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Tuple
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from pqblocks_files.pqtypes import TagVerificationFailed
+
+CHUNK_SIZE = 65536  # 64 KiB
+
+
+def _derive_payload_key(file_key: bytes, chunk_nonce: bytes) -> bytes:
+    """HKDF-SHA256(file_key, salt=chunk_nonce, info="payload") -> 32B."""
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=chunk_nonce,
+        info=b"payload",
+    )
+    return hkdf.derive(file_key)
+
+
+def _make_nonce(counter: int, is_final: bool) -> bytes:
+    """Construct 12-byte nonce from counter and final flag."""
+    flag = 0x01 if is_final else 0x00
+    return counter.to_bytes(8, "big") + bytes([flag]) + b"\x00\x00\x00"
+
+
+def _chunk(plaintext: bytes, file_key: bytes) -> List[Tuple[bytes, bytes]]:
+    """Encrypt plaintext into chunks.
+
+    Args:
+        plaintext: Data to encrypt
+        file_key: 16-byte key for HKDF derivation
+
+    Returns:
+        List of (nonce: 12B, ciphertext||tag: 16B tag) tuples
+
+    Contract:
+      - Number of chunks = ceil(len(plaintext) / 65536)
+      - Each chunk max 65536 bytes ciphertext
+      - For empty file: 1 chunk with 0-byte ciphertext + 16-byte tag
+      - Nonce counter starts at 0, increments per chunk
+      - Final chunk has flag=0x01
+    """
+    if not isinstance(plaintext, bytes):
+        raise TypeError(f"plaintext must be bytes, got {type(plaintext).__name__}")
+    if len(file_key) != 16:
+        raise ValueError(f"file_key must be 16 bytes, got {len(file_key)}")
+
+    # Handle empty plaintext: 1 chunk with 0-byte ciphertext
+    if not plaintext:
+        nonce = _make_nonce(0, True)
+        key = _derive_payload_key(file_key, nonce)
+        aead = ChaCha20Poly1305(key)
+        ct_and_tag = aead.encrypt(nonce, b"", b"")
+        return [(nonce, ct_and_tag)]
+
+    # Split into chunks
+    num_chunks = (len(plaintext) + CHUNK_SIZE - 1) // CHUNK_SIZE
+
+    result: List[Tuple[bytes, bytes]] = []
+    for i in range(num_chunks):
+        is_final = (i == num_chunks - 1)
+        nonce = _make_nonce(i, is_final)
+        chunk_pt = plaintext[i * CHUNK_SIZE : (i + 1) * CHUNK_SIZE]
+
+        key = _derive_payload_key(file_key, nonce)
+        aead = ChaCha20Poly1305(key)
+        ct_and_tag = aead.encrypt(nonce, chunk_pt, b"")
+
+        result.append((nonce, ct_and_tag))
+
+    return result
+
+
+def _unchunk(
+    chunked: List[Tuple[bytes, bytes]], file_key: bytes
+) -> bytes:
+    """Private test helper: decrypt chunks back to plaintext.
+
+    Trusts the nonces it is given (no order, final-flag or empty-input checks); the public
+    decrypt() enforces those. Not part of the API.
+
+    Args:
+        chunked: List of (nonce: 12B, ciphertext||tag) tuples
+        file_key: 16-byte key for HKDF derivation
+
+    Returns:
+        Original plaintext
+
+    Raises:
+        TagVerificationFailed: If any chunk's Poly1305 tag doesn't verify
+    """
+    if not chunked:
+        return b""
+
+    plaintext = b""
+    for nonce, ct_and_tag in chunked:
+        key = _derive_payload_key(file_key, nonce)
+        aead = ChaCha20Poly1305(key)
+        try:
+            pt = aead.decrypt(nonce, ct_and_tag, b"")
+        except Exception as e:
+            raise TagVerificationFailed(f"chunk decryption failed: {e}") from e
+        plaintext += pt
+
+    return plaintext

pqblocks_files/cli.py

@@ -0,0 +1,240 @@
+"""Command-line interface.
+
+  pqblocks-files keygen [--output pub.sec] [--output-sec priv.sec] [--passphrase-file FILE] [--classical]
+  pqblocks-files encrypt --recipient pub.sec [--recipient pub2.sec] [--output out.pfsh] [--classical] [-]
+  pqblocks-files decrypt --key priv.sec [--passphrase-file FILE] [--allow-classical] [--output out.bin] in.pfsh
+
+The private-key passphrase is read from a terminal prompt (getpass) or from --passphrase-file.
+It is never taken from an argument, never has a default, and is never printed.
+
+Exit codes:
+  0 = Success
+  1 = Bad input / malformed file / MAC failure / unusable passphrase
+  2 = Key not found in header / private key could not be unlocked
+  3 = ML-KEM key-check abort
+  4 = File is classical-only (not post-quantum) and --allow-classical was not given
+"""
+
+from __future__ import annotations
+
+import getpass
+import sys
+from argparse import ArgumentParser, Namespace
+from typing import List, Optional
+
+from pqblocks_files.encrypt import MODE_CLASSICAL, decrypt_with_mode, encrypt
+from pqblocks_files.keys import (
+    keygen,
+    load_private_key,
+    load_public_key,
+    public_key_text,
+    save_private_key,
+    save_public_key,
+)
+from pqblocks_files.pqtypes import (
+    ClassicalOnlyRejected,
+    HeaderMACMismatch,
+    KeyPair,
+    MLKEMKeyCheckFailed,
+    Recipient,
+    TagVerificationFailed,
+    TruncatedFile,
+)
+
+_MAX_PASSPHRASE_FILE = 4096
+
+
+def _read_passphrase_file(path: str) -> bytes:
+    """Contents of the file minus one trailing newline. Refuses an empty passphrase."""
+    with open(path, "rb") as fh:
+        data = fh.read(_MAX_PASSPHRASE_FILE + 1)
+    if len(data) > _MAX_PASSPHRASE_FILE:
+        raise ValueError(f"passphrase file is larger than {_MAX_PASSPHRASE_FILE} bytes")
+    if data.endswith(b"\r\n"):
+        data = data[:-2]
+    elif data.endswith(b"\n"):
+        data = data[:-1]
+    if not data:
+        raise ValueError("passphrase file is empty")
+    return data
+
+
+def _get_passphrase(args: Namespace, confirm: bool) -> bytes:
+    """Passphrase from --passphrase-file, else an interactive prompt. Never empty."""
+    if args.passphrase_file:
+        return _read_passphrase_file(args.passphrase_file)
+    first = getpass.getpass("Passphrase: ")
+    if confirm and getpass.getpass("Repeat passphrase: ") != first:
+        raise ValueError("passphrases do not match")
+    if not first:
+        raise ValueError("passphrase must not be empty")
+    return first.encode("utf-8")
+
+
+def _cmd_keygen(args: Namespace) -> int:
+    """Generate a keypair."""
+    passphrase: Optional[bytes] = None
+    if args.output_sec:
+        try:
+            passphrase = _get_passphrase(args, confirm=True)
+        except (OSError, ValueError) as exc:
+            print(f"Passphrase error: {exc}", file=sys.stderr)
+            return 1
+    kp = keygen(classical_only=args.classical)
+
+    try:
+        if args.output_sec:
+            save_private_key(kp, args.output_sec, passphrase)
+            print(f"Private key written to {args.output_sec}", file=sys.stderr)
+        else:
+            print("Warning: no --output-sec given, the private key is discarded", file=sys.stderr)
+        if args.output:
+            save_public_key(kp, args.output)
+            print(f"Public key written to {args.output}", file=sys.stderr)
+        else:
+            print(public_key_text(kp))
+    except OSError as exc:
+        print(f"Failed to write key file: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_encrypt(args: Namespace) -> int:
+    """Encrypt a file."""
+    recipients: List[Recipient] = []
+    for rec_path in args.recipient:
+        try:
+            recipients.append(load_public_key(rec_path))
+        except (OSError, ValueError) as exc:
+            print(f"Failed to load recipient {rec_path}: {exc}", file=sys.stderr)
+            return 1
+
+    if args.input == "-":
+        plaintext = sys.stdin.buffer.read()
+    else:
+        try:
+            with open(args.input, "rb") as f:
+                plaintext = f.read()
+        except FileNotFoundError as exc:
+            print(f"Input file not found: {exc}", file=sys.stderr)
+            return 1
+
+    try:
+        encrypted = encrypt(plaintext, recipients, classical_only=args.classical)
+    except Exception as exc:
+        print(f"Encryption failed: {exc}", file=sys.stderr)
+        return 1
+
+    return _write_output(args.output, encrypted, "Encrypted file")
+
+
+def _write_output(output_path: Optional[str], data: bytes, label: str) -> int:
+    if output_path and output_path != "-":
+        try:
+            with open(output_path, "wb") as f:
+                f.write(data)
+            print(f"{label} written to {output_path}", file=sys.stderr)
+        except IOError as exc:
+            print(f"Failed to write output: {exc}", file=sys.stderr)
+            return 1
+    else:
+        sys.stdout.buffer.write(data)
+    return 0
+
+
+def _cmd_decrypt(args: Namespace) -> int:
+    """Decrypt a file."""
+    from pqblocks_files.kem import HYBRID_PK_LEN
+
+    try:
+        passphrase = _get_passphrase(args, confirm=False)
+    except (OSError, ValueError) as exc:
+        print(f"Passphrase error: {exc}", file=sys.stderr)
+        return 1
+    try:
+        private = load_private_key(args.key, passphrase)
+    except FileNotFoundError:
+        print(f"Private key file not found: {args.key}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f"Failed to load key: {exc}", file=sys.stderr)
+        return 2
+    # decrypt() matches stanzas with the private key only; the public half is a placeholder.
+    keypair = KeyPair(public=Recipient(hybrid_pk=b"\x00" * HYBRID_PK_LEN), private=private)
+
+    try:
+        with open(args.input, "rb") as f:
+            pfsh_bytes = f.read()
+    except FileNotFoundError as exc:
+        print(f"Input file not found: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        result = decrypt_with_mode(pfsh_bytes, keypair, require_pq=not args.allow_classical)
+    except ClassicalOnlyRejected:
+        print(
+            "File is classical-only (X25519, not post-quantum). "
+            "Re-run with --allow-classical to accept it.",
+            file=sys.stderr,
+        )
+        return 4
+    except HeaderMACMismatch:
+        print("Key not found in header", file=sys.stderr)
+        return 2
+    except TagVerificationFailed as exc:
+        print(f"Tag verification failed: {exc}", file=sys.stderr)
+        return 1
+    except MLKEMKeyCheckFailed as exc:
+        print(f"ML-KEM key-check failed: {exc}", file=sys.stderr)
+        return 3
+    except TruncatedFile as exc:
+        print(f"Truncated file: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:
+        print(f"Decryption failed: {exc}", file=sys.stderr)
+        return 1
+
+    if result.mode == MODE_CLASSICAL:
+        print("Note: opened through a classical-only (X25519) stanza; not post-quantum protected.",
+              file=sys.stderr)
+    return _write_output(args.output, result.plaintext, "Decrypted file")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """CLI entry point. Returns exit code per contract."""
+    parser = ArgumentParser(prog="pqblocks-files")
+    subparsers = parser.add_subparsers(dest="command")
+
+    keygen_parser = subparsers.add_parser("keygen", help="Generate a keypair")
+    keygen_parser.add_argument("--output", "-o", help="Public key output path (default: print to stdout)")
+    keygen_parser.add_argument("--output-sec", help="Private key output path (encrypted under a passphrase)")
+    keygen_parser.add_argument("--passphrase-file", help="Read the private-key passphrase from this file instead of prompting")
+    keygen_parser.add_argument("--classical", action="store_true", help="X25519-only key (no post-quantum protection)")
+
+    encrypt_parser = subparsers.add_parser("encrypt", help="Encrypt a file")
+    encrypt_parser.add_argument("--recipient", "-r", required=True, action="append", help="Public key file(s)")
+    encrypt_parser.add_argument("--output", "-o", help="Output file path")
+    encrypt_parser.add_argument("--classical", action="store_true", help="X25519-only stanzas (no post-quantum protection)")
+    encrypt_parser.add_argument("input", help="Input file or '-' for stdin")
+
+    decrypt_parser = subparsers.add_parser("decrypt", help="Decrypt a file")
+    decrypt_parser.add_argument("--key", "-k", required=True, help="Private key file")
+    decrypt_parser.add_argument("--passphrase-file", help="Read the private-key passphrase from this file instead of prompting")
+    decrypt_parser.add_argument("--allow-classical", action="store_true", help="Accept files that are only readable through a classical-only (X25519) stanza")
+    decrypt_parser.add_argument("--output", "-o", help="Output file path")
+    decrypt_parser.add_argument("input", help="Input file")
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 1
+    if args.command == "keygen":
+        return _cmd_keygen(args)
+    if args.command == "encrypt":
+        return _cmd_encrypt(args)
+    return _cmd_decrypt(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())