Skip to content

key file system

Jump to bottom
Cyber Official edited this page May 31, 2026 · 1 revision

Key File System Deep Dive

Overview

The Key File System is a critical security feature in CyberPatchMaker that prevents users from applying patches to the wrong version or entirely different application. This document provides a comprehensive deep dive into how key files work, how they are specified, and advanced usage scenarios.

Purpose and Benefits

Why Key Files?

Without key file verification, several problematic scenarios could occur:

  1. Wrong Version: User tries to apply 1.0.1→1.0.3 patch to version 1.0.2
  2. Different Application: User tries to apply "GameX" patch to "GameY"
  3. Corrupted Installation: Modified or incomplete installation accepts patch
  4. Renamed Directories: User moves/renames folders and loses version tracking

Key files solve these problems by using a designated file's SHA-256 hash as the unique version identifier, independent of:

  • Directory names or locations
  • File system paths
  • Registry entries or metadata
  • User-provided version strings

Security Benefits

  • Tamper Detection: Any modification to the key file changes its hash
  • Version Authentication: Cryptographic proof of exact version
  • Cross-Platform: Works consistently across Windows, macOS, Linux
  • No External Dependencies: Self-contained verification

Key File Concept

What is a Key File?

A key file is any designated file (typically the main program or a critical component) that serves as the version's fingerprint. Properties:

  • Path: Relative path from version root (e.g., program.exe, bin/app.exe, core.dll, data.bin)
  • Checksum: SHA-256 hash of the file's binary content
  • Size: File size in bytes (stored for reference; not used in verification)
  • File Type: Can be any file type - executables, libraries, data files, configuration files, etc.

Version Identification

Version 1.0.0:
  Key File: program.exe
  Checksum: a1b2c3d4e5f6...
  
Version 1.0.1:
  Key File: program.exe
  Checksum: x9y8z7w6v5u4...  ← Different hash = different version

Even if the filename is identical (program.exe), the hash uniquely identifies each version.

Key File Selection

Auto-Detection from Common Names

When no --key-file flag is provided, the generator automatically looks for a key file by checking for the following common names in the version directory root (in order):

  1. program.exe
  2. game.exe
  3. app.exe
  4. main.exe

If one of these files is found, it is used as the key file. If none are found, patch generation fails with an error:

Error: could not find key file (program.exe, game.exe, app.exe, or main.exe)
Hint: Use --key-file to specify a custom key file

Manual Override with --key-file

The --key-file flag allows specifying any file as the key file, regardless of its name or type:

# Generator: specify custom key file
patch-gen.exe --from-dir "D:\releases\1.0.0" --to-dir "D:\releases\1.0.3" --key-file "myapp.exe" --output "patches"

# Applier: override key file at apply time (if renamed or moved)
patch-apply.exe --patch patch.patch --current-dir C:\MyApp --key-file "renamed.exe"

Interactive Menu (Applier)

When running a self-contained executable in interactive mode, the menu offers a "Specify Custom Key File" option (option 5) that allows the user to provide a custom key file path without restarting.

Key File Verification Workflow

During Patch Generation

Version registration happens automatically when you generate patches. The system:

1. User runs: patch-gen.exe --from-dir "D:\releases\1.0.0" --to-dir "D:\releases\1.0.3" --output "patches"

2. System determines key file:
   - If --key-file provided → use that file
   - Otherwise → auto-detect by checking program.exe, game.exe, app.exe, main.exe

3. System scans source directory (1.0.0):
   - Calculate SHA-256 of key file → "a1b2c3d4e5f6..."
   - Create full file manifest

4. System scans target directory (1.0.3):
   - Calculate SHA-256 of key file → "xyz789..."
   - Create full file manifest

5. System embeds key file info in patch metadata

Note: There is no separate "register" command. Versions are registered automatically during patch generation.

During Patch Generation

1. Load source manifest (1.0.0) → key_file: "program.exe" (hash: abc123...)
2. Load target manifest (1.0.3) → key_file: "program.exe" (hash: xyz789...)
3. Embed in patch:
   {
     "from_key_file": {
       "path": "program.exe",
       "checksum": "abc123...",
       "size": 14680064
     },
     "to_key_file": {
       "path": "program.exe",
       "checksum": "xyz789...",
       "size": 15728640
     }
   }

Key File Metadata in Patch

1. Read patch metadata:
   - Required key file: "program.exe"
   - Required hash: "abc123..."

2. Find key file in target directory:
   - Look at: C:\MyApp\program.exe
   - Or use --key-file override if provided

3. Calculate current hash:
   - SHA-256(C:\MyApp\program.exe) → "abc123..."

4. Compare:
   if currentHash != requiredHash {
       REJECT PATCH → "key file checksum mismatch: expected abc123..., got xyz789..."
   }

5. If match → Proceed with patch application

Advanced Scenarios

Multi-Executable Applications

Problem: Application has multiple executables (game.exe, launcher.exe, server.exe)

Solution: Use the --key-file flag to explicitly specify which file should serve as the key file. Only files matching the auto-detected names (program.exe, game.exe, app.exe, main.exe) will be found automatically.

Example:

MyGame/
├── launcher.exe      (2MB)
├── game.exe          (250MB) ← Auto-detected as key file
└── tools/
    └── editor.exe    (50MB)

Custom Key File Paths

Problem: Main file is in a non-standard location or has a non-standard name

Example:

Application/
├── data/
└── bin/
    └── myapp.exe     ← Main executable here

Solution: Use the --key-file flag to specify the custom file name:

patch-gen.exe --from-dir "./1.0.0" --to-dir "./1.0.1" --key-file "bin/myapp.exe" --output "patches"

Platform-Specific Key Files

Problem: Cross-platform application with different executables per platform

Example:

MyApp/
├── windows/
│   └── app.exe       ← Windows key file
├── macos/
│   └── app           ← macOS key file
└── linux/
    └── app           ← Linux key file

Solution: Generate separate patches per platform using --from-dir and --to-dir:

# Windows patches
patch-gen.exe --from-dir "./1.0.0/windows" --to-dir "./1.0.1/windows" --output "./patches/windows"

# macOS patches
patch-gen.exe --from-dir "./1.0.0/macos" --to-dir "./1.0.1/macos" --output "./patches/macos"

# Linux patches
patch-gen.exe --from-dir "./1.0.0/linux" --to-dir "./1.0.1/linux" --output "./patches/linux"

Note: Use --key-file to specify the correct key file for each platform (e.g., --key-file app.exe for Windows, --key-file app for macOS/Linux).

No Suitable Key File

Problem: Application has none of the auto-detected file names and no --key-file is specified

Example:

ScriptApp/
├── main.py           ← Entry point
├── config.json
└── modules/

Solution: Use --key-file to specify any file as the key file. The key file can be any file type - executables, libraries, data files, configuration files, etc.

Edge Cases and Troubleshooting

Case 1: No Key File Found

Symptom: Patch generation fails with "could not find key file (program.exe, game.exe, app.exe, or main.exe)" or manifest creation fails with "no files provided for manifest"

Causes:

  • Directory contains only data/script files
  • Key file has a non-standard name
  • Key file is in a subdirectory

Solutions:

  1. Use --key-file to specify the correct file name
  2. Verify the file exists in the version directory

Case 2: Multiple Suitable Candidates

Symptom: None of the auto-detected names match, or you want to use a specific file among many

Example:

MyApp/
├── client.exe    (150MB)
├── server.exe    (180MB)
└── admin.exe     (120MB)

Solutions:

  1. Use --key-file to explicitly specify which file to use as the key file
  2. Only program.exe, game.exe, app.exe, and main.exe are auto-detected

Case 3: Key File Modified

Symptom: Patch application fails with "key file checksum mismatch: expected ..., got ..."

Causes:

  • User modified executable (mod, crack, etc.)
  • Executable corrupted during download/copy
  • Wrong version installed
  • Anti-virus quarantined and restored executable

Solutions:

  1. Re-download clean version
  2. Verify with original installer
  3. Check anti-virus logs

Case 4: Renamed Key File

Symptom: Patch fails to find key file at expected path

Example:

Original:
  MyApp/program.exe

User renamed:
  MyApp/game.exe  ← Patch looks for "program.exe"

Solutions:

  • Prevention: Document that renaming the key file breaks patching
  • Recovery: Restore original filename before patching
  • Override: Use --key-file flag in the applier to specify the new name
  • Interactive: Use "Specify Custom Key File" (option 5) in the interactive menu

Performance Considerations

Hash Calculation

  • Hash calculated once during version registration
  • Cached in manifest (no recalculation needed)
  • Only recalculated during patch verification

Security Considerations

Hash Collision Resistance

SHA-256 Properties:

  • 256-bit hash space (2^256 possible values)
  • Collision probability: negligible (1 in 2^128)
  • Pre-image resistance: computationally infeasible to find matching file

Practical Security:

  • No known SHA-256 collisions for real-world executables
  • Quantum computers would need ~10^20 operations (not practical)
  • More secure than MD5/SHA-1 (both have known collisions)

Tampering Detection

Attack Scenario: Attacker modifies executable to inject malware

Protection:

Original:
  program.exe → SHA-256: abc123... (clean)

Tampered:
  program.exe → SHA-256: xyz789... (modified)

Patch Check:
  Expected: abc123...
  Got:      xyz789...
  RESULT: PATCH REJECTED ✓

Conclusion: Any byte-level modification to key file changes hash, preventing patch application.

Key File Spoofing

Attack Scenario: Attacker creates fake version with crafted key file

Protection:

  • Patches include BOTH source and target key file hashes
  • Attacker cannot generate executable with specific SHA-256 hash (pre-image resistance)
  • Even if attacker matches source hash, target hash must also match

Mitigation: Users should obtain patches only from trusted sources.

Best Practices

For Developers

  1. Consistent Naming: Use consistent key file names across versions
  2. Use Standard Names: Name the key file program.exe, game.exe, app.exe, or main.exe for auto-detection
  3. Avoid Renaming: Don't rename the key file between versions
  4. Document Key File: Clearly document which file is the key file

For Users

  1. Don't Modify: Never modify the key file manually
  2. Restore Original: If modified, restore original before patching
  3. Verify Source: Obtain patches only from trusted/official sources
  4. Check Errors: Read error messages carefully - they explain key file mismatches
  5. Custom Key File: Use --key-file if the key file was renamed or moved

For System Administrators

  1. Standard Names: Use one of program.exe, game.exe, app.exe, or main.exe for auto-detection
  2. Manual Override: Use --key-file when the key file has a non-standard name
  3. Document Overrides: Record any custom key file specifications
  4. Verify Manifests: Periodically verify manifests match actual installations

Summary

The Key File System is a critical security feature that:

  • Prevents wrong patch application (version mismatch detection)
  • Detects tampering (any modification changes hash)
  • Works cross-platform (SHA-256 is universal)
  • Requires no external dependencies (self-contained verification)
  • Provides clear error messages (users understand why patch failed)

By using SHA-256 hashes of designated files as version identifiers, CyberPatchMaker ensures cryptographic-strength verification that patches are applied to exactly the correct version.

See Also

Clone this wiki locally