gun101 1.2.0__py3-none-any.whl

gun101/__init__.py

@@ -0,0 +1,47 @@
+"""
+GUN101 PDF Encryption Protocol Suite
+
+Two encryption modes:
+
+  GUN101 (password-based)
+    AES-256-GCM with Argon2/PBKDF2 key derivation, time-based cryptographic
+    challenge, and rate-limiting brute-force protection.
+
+  GUN101-GKP (Ghost Key Protocol — identity/asymmetric mode)
+    RSA-4096 key wrapping via the recipient's public Identity Token.
+    No shared password required. Only the recipient's physical device
+    (holding the matching GKP private key) can decrypt the file.
+"""
+
+from .config import security_config
+from .crypto_engine import CryptoEngine
+from .key_manager import KeyManager
+from .security_layer import SecurityLayer
+from .pdf_handler import PDFEncryptionHandler
+from .identity import IdentityManager
+from .utils import (
+    generate_salt,
+    generate_nonce,
+    get_current_timestamp,
+    verify_password_hash,
+    create_fingerprint
+)
+
+__version__ = "1.2.0"
+__author__ = "Security Team"
+__protocol__ = "GUN101"
+__gkp_protocol__ = "GUN101-GKP"
+
+__all__ = [
+    "PDFEncryptionHandler",
+    "IdentityManager",
+    "CryptoEngine",
+    "KeyManager",
+    "SecurityLayer",
+    "security_config",
+    "generate_salt",
+    "generate_nonce",
+    "get_current_timestamp",
+    "verify_password_hash",
+    "create_fingerprint"
+]

gun101/cli.py

@@ -0,0 +1,331 @@
+"""
+GUN101 Command Line Interface
+
+Usage:
+    gun101 help                                   Show all available commands
+    gun101 encrypt <file>                         Encrypt a PDF with a password (GUN101)
+    gun101 encrypt <file> --recipient <token>     Encrypt for a specific recipient (GUN101-GKP)
+    gun101 decrypt <file>                         Decrypt a file (auto-detects GUN101 vs GKP)
+    gun101 generate-identity                      Generate your GKP Identity Token
+    gun101 show-identity                          Display your GKP Identity Token
+    gun101 reset-identity                         Delete your GKP identity (WARNING: irreversible)
+"""
+import argparse
+import sys
+import json
+import getpass
+from pathlib import Path
+
+from gun101 import PDFEncryptionHandler
+from gun101.identity import IdentityManager
+from gun101.config import security_config
+
+
+# ── Styling helpers ──────────────────────────────────────────────────────────
+
+def _banner():
+    print()
+    print("╔══════════════════════════════════════════════════════════╗")
+    print("║          GUN101  PDF Encryption Protocol Suite         ║")
+    print("║  Password · GKP (Ghost Key Protocol) · AES-256-GCM     ║")
+    print("╚══════════════════════════════════════════════════════════╝")
+    print()
+
+
+def _success(msg):
+    print(f"  ✓ {msg}")
+
+
+def _error(msg):
+    print(f"  ✗ {msg}", file=sys.stderr)
+
+
+def _info(msg):
+    print(f"  ℹ {msg}")
+
+
+# ── Command implementations ─────────────────────────────────────────────────
+
+def help_command(args):
+    """Show detailed help for all GUN101 commands."""
+    _banner()
+    print("COMMANDS")
+    print("────────────────────────────────────────────────────────────")
+    print()
+    print("  gun101 help")
+    print("      Show this help message with all available commands.")
+    print()
+    print("  gun101 encrypt <file> [-o OUTPUT]")
+    print("      Encrypt a PDF file using a password (GUN101 mode).")
+    print("      You will be securely prompted to enter and confirm")
+    print("      your password (it will not appear on screen).")
+    print()
+    print("  gun101 encrypt <file> --recipient <IDENTITY_TOKEN> [-o OUTPUT]")
+    print("      Encrypt a PDF using GUN101-GKP (Ghost Key Protocol).")
+    print("      No password is needed. Only the recipient's physical")
+    print("      device, which holds the matching GKP private key,")
+    print("      can decrypt the file.")
+    print()
+    print("  gun101 decrypt <file> [-o OUTPUT]")
+    print("      Decrypt a GUN101 or GKP-encrypted file. The tool")
+    print("      auto-detects the mode and handles it accordingly.")
+    print()
+    print("  gun101 generate-identity")
+    print("      Generate your device's GKP (Ghost Key Protocol) identity.")
+    print("      An RSA-4096 keypair is created. The private key is")
+    print("      stored securely on this device and never leaves it.")
+    print("      The public Identity Token is displayed for sharing.")
+    print()
+    print("  gun101 show-identity")
+    print("      Display your existing GKP Identity Token and its")
+    print("      fingerprint so you can share it with senders.")
+    print()
+    print("  gun101 reset-identity")
+    print("      Delete your GKP identity from this device.")
+    print("      WARNING: Any GKP-encrypted files targeting this")
+    print("      identity will become PERMANENTLY UNRECOVERABLE.")
+    print()
+    print("OPTIONS")
+    print("────────────────────────────────────────────────────────────")
+    print("  -o, --output PATH     Custom output file path")
+    print("  --recipient TOKEN     Recipient's GKP Identity Token (for GKP mode)")
+    print()
+    print("EXAMPLES")
+    print("────────────────────────────────────────────────────────────")
+    print("  # Password-based encryption (GUN101)")
+    print("  gun101 encrypt report.pdf")
+    print("  gun101 decrypt report.pdf.encrypted")
+    print()
+    print("  # Identity-based encryption (GUN101-GKP — no password needed)")
+    print("  gun101 generate-identity")
+    print("  gun101 show-identity                  # share your token with the sender")
+    print("  gun101 encrypt report.pdf --recipient <Identity_Token>")
+    print("  gun101 decrypt report.pdf.encrypted   # run on your device to decrypt")
+    print()
+
+
+def encrypt_command(args):
+    """Encrypt a PDF file."""
+    try:
+        input_path = Path(args.input)
+        if not input_path.exists():
+            _error(f"File not found: {args.input}")
+            sys.exit(1)
+
+        with open(input_path, "rb") as f:
+            data = f.read()
+
+        handler = PDFEncryptionHandler()
+        output_path = args.output if args.output else str(input_path) + ".encrypted"
+
+        if args.recipient:
+            # ── GUN101-GKP (Ghost Key Protocol) ──
+            _info("Encrypting with GUN101-GKP (Ghost Key Protocol)...")
+            _info("Recipient's device is the only one that can decrypt this file.")
+            encrypted_data = handler.encrypt_pdf_for_recipient(data, args.recipient)
+            with open(output_path, "wb") as f:
+                f.write(encrypted_data)
+            _success(f"GKP-locked file saved to {output_path}")
+            _info("Only the recipient's physical device can decrypt this file.")
+        else:
+            # ── GUN101 password mode ──
+            password = getpass.getpass("  Enter password for encryption: ")
+            confirm = getpass.getpass("  Confirm password: ")
+            if password != confirm:
+                _error("Passwords do not match.")
+                sys.exit(1)
+
+            encrypted_data = handler.encrypt_pdf(data, password)
+            with open(output_path, "wb") as f:
+                f.write(encrypted_data)
+            _success(f"Password-locked file saved to {output_path}")
+
+    except Exception as e:
+        _error(f"Encryption failed: {e}")
+        sys.exit(1)
+
+
+def decrypt_command(args):
+    """Decrypt a GUN101 or GKP-encrypted file (auto-detects mode)."""
+    try:
+        input_path = Path(args.input)
+        if not input_path.exists():
+            _error(f"File not found: {args.input}")
+            sys.exit(1)
+
+        with open(input_path, "rb") as f:
+            data = f.read()
+
+        # Auto-detect lock mode from the container
+        try:
+            container = json.loads(data.decode("utf-8"))
+            lock_mode = container.get("lock_mode", "password")
+        except Exception:
+            lock_mode = "password"
+
+        handler = PDFEncryptionHandler()
+        output_path = args.output if args.output else str(input_path).replace(
+            ".encrypted", ".decrypted.pdf"
+        )
+
+        if lock_mode == security_config.GKP_LOCK_MODE:
+            # ── GUN101-GKP decryption ──
+            _info("GKP-locked file detected (Ghost Key Protocol). Using device private key...")
+            decrypted_data, metadata = handler.decrypt_pdf_identity(data)
+            with open(output_path, "wb") as f:
+                f.write(decrypted_data)
+            _success(f"Decrypted file saved to {output_path}")
+            if metadata:
+                _info(f"Metadata recovered: {metadata}")
+        else:
+            # ── GUN101 password decryption ──
+            password = getpass.getpass("  Enter password for decryption: ")
+            decrypted_data, metadata = handler.decrypt_pdf(data, password)
+            with open(output_path, "wb") as f:
+                f.write(decrypted_data)
+            _success(f"Decrypted file saved to {output_path}")
+            if metadata:
+                _info(f"Metadata recovered: {metadata}")
+
+    except ValueError as e:
+        _error(f"Decryption failed: {e}")
+        sys.exit(1)
+    except Exception as e:
+        _error(f"An error occurred: {e}")
+        sys.exit(1)
+
+
+def generate_identity_command(args):
+    """Generate a new GKP device Identity Token."""
+    _banner()
+    try:
+        manager = IdentityManager()
+
+        passphrase = None
+        response = input("  Protect GKP private key with a passphrase? (y/N): ").strip().lower()
+        if response == "y":
+            passphrase = getpass.getpass("  Enter passphrase: ")
+            confirm = getpass.getpass("  Confirm passphrase: ")
+            if passphrase != confirm:
+                _error("Passphrases do not match.")
+                sys.exit(1)
+
+        _info("Generating RSA-4096 GKP keypair... (this may take a moment)")
+        token = manager.generate_identity(passphrase)
+        fingerprint = manager.get_identity_fingerprint(token)
+
+        _success("GKP identity generated successfully!")
+        print()
+        print("  Your GKP Identity Token (share this with senders):")
+        print(f"  {token[:80]}...")
+        print()
+        print(f"  Fingerprint: {fingerprint}")
+        print()
+        _info("Your private key is stored securely on this device.")
+        _info("Run 'gun101 show-identity' to see the full token anytime.")
+
+    except FileExistsError as e:
+        _error(str(e))
+        sys.exit(1)
+    except Exception as e:
+        _error(f"GKP identity generation failed: {e}")
+        sys.exit(1)
+
+
+def show_identity_command(args):
+    """Display the current device GKP Identity Token."""
+    try:
+        manager = IdentityManager()
+        token = manager.get_identity_token()
+        fingerprint = manager.get_identity_fingerprint(token)
+
+        _banner()
+        print("  Your GKP Identity Token:")
+        print(f"  {token}")
+        print()
+        print(f"  Fingerprint: {fingerprint}")
+        print()
+        _info("Share the token above with anyone who wants to send you a GKP-encrypted file.")
+
+    except FileNotFoundError as e:
+        _error(str(e))
+        sys.exit(1)
+
+
+def reset_identity_command(args):
+    """Delete the GKP device identity (irreversible)."""
+    _banner()
+    print("  ⚠  WARNING: This will permanently delete your GKP identity.")
+    print("     Any GKP-encrypted files targeting this identity will become")
+    print("     PERMANENTLY UNRECOVERABLE.")
+    print()
+    confirm = input("  Type 'DELETE' to confirm: ").strip()
+    if confirm != "DELETE":
+        _info("Reset cancelled.")
+        return
+
+    manager = IdentityManager()
+    manager.reset_identity()
+    _success("GKP identity has been deleted from this device.")
+
+
+# ── CLI entry point ──────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="gun101",
+        description=(
+            "GUN101 PDF Encryption Protocol Suite — "
+            "Password (GUN101) · Ghost Key Protocol (GKP) · AES-256-GCM"
+        ),
+        add_help=False
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # gun101 help
+    help_parser = subparsers.add_parser("help", help="Show all available commands and usage")
+    help_parser.set_defaults(func=help_command)
+
+    # gun101 encrypt
+    encrypt_parser = subparsers.add_parser("encrypt", help="Encrypt a PDF file")
+    encrypt_parser.add_argument("input", help="Path to the PDF file")
+    encrypt_parser.add_argument("-o", "--output", help="Custom output file path")
+    encrypt_parser.add_argument(
+        "--recipient",
+        help="Recipient's GKP Identity Token (enables GUN101-GKP mode)",
+        default=None
+    )
+    encrypt_parser.set_defaults(func=encrypt_command)
+
+    # gun101 decrypt
+    decrypt_parser = subparsers.add_parser("decrypt", help="Decrypt a GUN101 or GKP-encrypted file")
+    decrypt_parser.add_argument("input", help="Path to the encrypted file")
+    decrypt_parser.add_argument("-o", "--output", help="Custom output file path")
+    decrypt_parser.set_defaults(func=decrypt_command)
+
+    # gun101 generate-identity
+    gen_parser = subparsers.add_parser(
+        "generate-identity", help="Generate your GKP (Ghost Key Protocol) Identity Token"
+    )
+    gen_parser.set_defaults(func=generate_identity_command)
+
+    # gun101 show-identity
+    show_parser = subparsers.add_parser("show-identity", help="Display your GKP Identity Token")
+    show_parser.set_defaults(func=show_identity_command)
+
+    # gun101 reset-identity
+    reset_parser = subparsers.add_parser(
+        "reset-identity", help="Delete your GKP identity (irreversible)"
+    )
+    reset_parser.set_defaults(func=reset_identity_command)
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        help_command(args)
+    else:
+        args.func(args)
+
+
+if __name__ == "__main__":
+    main()

gun101/config.py

@@ -0,0 +1,43 @@
+"""
+Configuration and security constants for PDF encryption layer
+"""
+from datetime import timedelta
+
+
+class SecurityConfig:
+    """Security configuration for PDF encryption"""
+    
+    # GUN101 Protocol: Time-Based Cryptographic Challenge (umbrella protocol)
+    ENCRYPTION_PROTOCOL = "GUN101"
+    ENCRYPTION_ALGORITHM = "AES-256-GCM"
+    KEY_SIZE = 32  # 256 bits
+
+    # GUN101-GKP: Ghost Key Protocol (identity/asymmetric sub-protocol)
+    GKP_PROTOCOL = "GUN101-GKP"
+    GKP_LOCK_MODE = "GKP"  # value stored in container's lock_mode field
+
+    # Argon2 key derivation parameters
+    ARGON2_TIME_COST = 4  # iterations
+    ARGON2_MEMORY_COST = 128  # MB
+    ARGON2_PARALLELISM = 4  # threads
+    ARGON2_SALT_LENGTH = 16  # bytes
+    
+    # Additional security layers
+    NONCE_LENGTH = 12  # bytes for GCM mode
+    TAG_LENGTH = 16  # bytes for GCM authentication tag
+    
+    # Rate limiting
+    MAX_DECRYPTION_ATTEMPTS = 5
+    LOCKOUT_DURATION = timedelta(minutes=15)
+    ATTEMPT_RESET_DURATION = timedelta(hours=1)
+    
+    # Timestamp-based security
+    ENABLE_TIMESTAMP_VALIDATION = True
+    TIMESTAMP_TOLERANCE = 300  # seconds (5 minutes)
+    
+    # Key stretching iterations
+    KEY_STRETCH_ITERATIONS = 100000
+
+
+# Load configuration
+security_config = SecurityConfig()

gun101/crypto_engine.py

@@ -0,0 +1,129 @@
+"""
+AES-256 GCM encryption engine
+Provides secure encryption and decryption operations
+"""
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+import os
+from typing import Tuple
+from .config import security_config
+from .utils import generate_nonce, generate_salt
+
+
+class CryptoEngine:
+    """AES-256-GCM encryption engine"""
+    
+    def __init__(self):
+        self.key_size = security_config.KEY_SIZE
+        self.nonce_length = security_config.NONCE_LENGTH
+        self.tag_length = security_config.TAG_LENGTH
+    
+    def encrypt(
+        self, 
+        data: bytes, 
+        encryption_key: bytes,
+        associated_data: bytes = None
+    ) -> Tuple[bytes, bytes, bytes]:
+        """
+        Encrypt data using AES-256-GCM
+        
+        Args:
+            data: Data to encrypt
+            encryption_key: 256-bit encryption key
+            associated_data: Optional additional authenticated data (AAD)
+            
+        Returns:
+            Tuple of (nonce, ciphertext, tag)
+            Full encrypted data format: nonce + ciphertext + tag
+        """
+        if len(encryption_key) != self.key_size:
+            raise ValueError(f"Key must be {self.key_size} bytes, got {len(encryption_key)}")
+        
+        # Generate random nonce
+        nonce = generate_nonce(self.nonce_length)
+        
+        # Create cipher
+        cipher = AESGCM(encryption_key)
+        
+        # Encrypt with authentication
+        # GCM mode provides both confidentiality and authenticity
+        ciphertext = cipher.encrypt(nonce, data, associated_data)
+        
+        # In GCM, the tag is appended to ciphertext by cryptography library
+        # We need to separate it for flexibility
+        actual_ciphertext = ciphertext[:-self.tag_length]
+        tag = ciphertext[-self.tag_length:]
+        
+        return nonce, actual_ciphertext, tag
+    
+    def decrypt(
+        self,
+        nonce: bytes,
+        ciphertext: bytes,
+        tag: bytes,
+        encryption_key: bytes,
+        associated_data: bytes = None
+    ) -> bytes:
+        """
+        Decrypt data using AES-256-GCM
+        
+        Args:
+            nonce: Nonce used during encryption
+            ciphertext: Encrypted data (without tag)
+            tag: GCM authentication tag
+            encryption_key: 256-bit encryption key
+            associated_data: Optional additional authenticated data (AAD)
+            
+        Returns:
+            Decrypted plaintext data
+            
+        Raises:
+            cryptography.exceptions.InvalidTag: If authentication fails
+        """
+        if len(encryption_key) != self.key_size:
+            raise ValueError(f"Key must be {self.key_size} bytes, got {len(encryption_key)}")
+        
+        cipher = AESGCM(encryption_key)
+        
+        # Reconstruct ciphertext with tag for decryption
+        ciphertext_with_tag = ciphertext + tag
+        
+        try:
+            plaintext = cipher.decrypt(nonce, ciphertext_with_tag, associated_data)
+            return plaintext
+        except Exception as e:
+            raise ValueError(f"Decryption failed (possible tampering or wrong key): {str(e)}")
+    
+    def encrypt_to_bytes(
+        self,
+        data: bytes,
+        encryption_key: bytes,
+        associated_data: bytes = None
+    ) -> bytes:
+        """
+        Encrypt data and return as single byte string
+        Format: nonce (12 bytes) + ciphertext + tag (16 bytes)
+        """
+        nonce, ciphertext, tag = self.encrypt(data, encryption_key, associated_data)
+        return nonce + ciphertext + tag
+    
+    def decrypt_from_bytes(
+        self,
+        encrypted_data: bytes,
+        encryption_key: bytes,
+        associated_data: bytes = None
+    ) -> bytes:
+        """
+        Decrypt data from single byte string
+        Expects format: nonce (12 bytes) + ciphertext + tag (16 bytes)
+        """
+        nonce_length = self.nonce_length
+        tag_length = self.tag_length
+        
+        if len(encrypted_data) < nonce_length + tag_length:
+            raise ValueError("Encrypted data too short")
+        
+        nonce = encrypted_data[:nonce_length]
+        tag = encrypted_data[-tag_length:]
+        ciphertext = encrypted_data[nonce_length:-tag_length]
+        
+        return self.decrypt(nonce, ciphertext, tag, encryption_key, associated_data)