diff --git a/CBT-Format.md b/CBT-Format.md new file mode 100644 index 0000000..9edc148 --- /dev/null +++ b/CBT-Format.md @@ -0,0 +1,189 @@ +# CBT File Format + +## Overview + +**CBT** (Comic Book TAR) is a comic book archive format that uses TAR (Tape Archive) as the container format instead of ZIP. Gopherbook supports both unencrypted and AES-256 encrypted CBT files. + +## Format Specification + +### Basic Structure + +A CBT file is simply a TAR archive containing: +- Image files (JPEG, PNG, GIF, AVIF, JXL, WebP, BMP, JP2) +- `ComicInfo.xml` (optional metadata) + +### File Extensions + +- `.cbt` - Standard CBT file + +### Supported Image Formats + +- `.jpg`, `.jpeg` - JPEG images +- `.png` - PNG images +- `.gif` - GIF images +- `.avif` - AVIF images +- `.jxl` - JPEG XL images +- `.webp` - WebP images +- `.bmp` - Bitmap images +- `.jp2` - JPEG 2000 images + +## Encryption + +### Encryption Method + +Gopherbook uses **AES-256-CFB** (Cipher Feedback mode) for encryption: + +1. **Key Derivation**: SHA-256 hash of the password +2. **IV Generation**: Random 16-byte initialization vector +3. **Encryption**: AES-256-CFB on the entire TAR archive +4. **Storage**: IV prepended to ciphertext + +### Encrypted File Structure + +``` +[16 bytes IV][Encrypted TAR data...] +``` + +### Compatibility + +The encryption format is compatible with: +- OpenSSL command-line tools +- Gopherbook's Go implementation +- The provided bash script (`cbt.sh`) + +## ComicInfo.xml + +CBT files can include a `ComicInfo.xml` file for metadata. Gopherbook extracts: + +- **Title** - Comic title +- **Series** - Series name +- **Number** - Issue number +- **Writer** - Writer name +- **Artist** / **Inker** - Artist name +- **Publisher** - Publisher name +- **Genre** / **Tags** - Tags/genres +- **StoryArc** - Story arc name +- **Year** - Publication year +- **Month** - Publication month +- **Summary** - Description +- **PageCount** - Number of pages + +### Example ComicInfo.xml + +```xml + + + The Amazing Adventure + Super Comics + 42 + John Doe + Jane Smith + Comic Press + Action, Adventure + superhero, action + The Grand Quest + 2024 + 1 + An epic tale of heroism... + 24 + +``` + +## CBT vs CBZ + +### Advantages of CBT + +1. **Simpler Format**: TAR is simpler than ZIP +2. **Better for Streaming**: Sequential structure +3. **Unix-Friendly**: Native TAR tools on all Unix systems +4. **Compression Agnostic**: Images already compressed + +### Advantages of CBZ + +1. **More Common**: Wider software support +2. **Per-File Compression**: Can compress text metadata +3. **Random Access**: Easier to extract single files + +### When to Use CBT + +- Unix/Linux environments +- Streaming applications +- Encrypted archives (simpler encryption) +- Archival purposes + +### When to Use CBZ + +- Windows environments +- Maximum compatibility +- Need per-file compression +- Most comic readers + +## Creating CBT Files + +See the [Creating CBT Files](Creating-CBT-Files) page for detailed instructions using: +- The `cbt.sh` bash script +- The `cbt.go` Go program +- Manual TAR commands + +## Technical Details + +### Encryption Algorithm Details + +``` +Algorithm: AES-256-CFB +Key: SHA256(password) = 32 bytes +IV: Random 16 bytes +Block Size: 16 bytes (128 bits) +Mode: CFB (Cipher Feedback) +``` + +### Decryption Process + +1. Read first 16 bytes as IV +2. Read remaining bytes as ciphertext +3. Derive key from password using SHA-256 +4. Decrypt using AES-256-CFB with IV and key +5. Extract TAR archive from plaintext + +### Validation + +To check if a CBT is encrypted: + +```bash +# Try reading as TAR +tar -tf file.cbt + +# If it fails, likely encrypted +# If it succeeds, unencrypted +``` + +## File Organization + +Gopherbook automatically organizes CBT files: + +``` +library/ +└── [Artist]/ + └── [StoryArc]/ + └── comic.cbt +``` + +Based on extracted metadata from ComicInfo.xml. + +## Best Practices + +1. **Always include ComicInfo.xml** for proper metadata +2. **Use consistent naming** for images (001.jpg, 002.jpg, etc.) +3. **Encrypt sensitive content** using strong passwords +4. **Store passwords securely** (Gopherbook does this automatically) +5. **Backup your library** regularly + +## Related Pages + +- [Creating CBT Files](Creating-CBT-Files) +- [Bash Scripts](Bash-Scripts) +- [Password Protection](Password-Protection) + +--- + +**Note**: CBT support is a unique feature of Gopherbook. Most comic readers only support CBZ/CBR formats. diff --git a/Creating-CBT-Files.md b/Creating-CBT-Files.md new file mode 100644 index 0000000..6deaea2 --- /dev/null +++ b/Creating-CBT-Files.md @@ -0,0 +1,332 @@ +# Creating CBT Files + +This guide covers multiple methods for creating CBT (Comic Book TAR) files with or without encryption. + +## Method 1: Using the cbt.sh Bash Script (Recommended) + +### Prerequisites + +- Bash shell (Linux/Mac/WSL) +- OpenSSL +- Standard Unix tools (tar, sha256sum, xxd) + +### Installation + +The `cbt.sh` script is included in the `scripts-bash/comic-scripts/` directory: + +```bash +chmod +x scripts-bash/comic-scripts/cbt.sh +``` + +### Creating Unencrypted CBT + +```bash +./scripts-bash/comic-scripts/cbt.sh create -i /path/to/comic/images -o mycomic.cbt +``` + +**Example:** +```bash +./scripts-bash/comic-scripts/cbt.sh create -i ./my-comic-pages-folder -o amazing-comic.cbt +``` + +This will: +1. Create a TAR archive from all files in the directory +2. Save it as `amazing-comic.cbt` +3. Display list of files added + +### Creating Encrypted CBT + +```bash +./scripts-bash/comic-scripts/cbt.sh create -i /path/to/comic/images -o mycomic.cbt -p "your-password" +``` + +**Example:** +```bash +./scripts-bash/comic-scripts/cbt.sh create -i ./my-comic-pages-folder -o secret-comic.cbt -p "super-secret-123" +``` + +This will: +1. Create a TAR archive +2. Encrypt it using AES-256-CFB +3. Save the encrypted CBT file + +### Extracting CBT Files + +**Unencrypted:** +```bash +./scripts-bash/comic-scripts/cbt.sh extract -i mycomic.cbt -o ./extracted +``` + +**Encrypted:** +```bash +./scripts-bash/comic-scripts/cbt.sh extract -i secret-comic.cbt -o ./extracted -p "your-password" +``` + +### Script Options + +``` +Usage: + Create: cbt.sh create -i -o [-p ] + Extract: cbt.sh extract -i -o [-p ] + +Options: + -i Input directory/file + -o Output file/directory + -p Password for encryption/decryption (optional) +``` + +## Method 2: Using the cbt.go Program + +### Prerequisites + +- Go 1.25.2 or higher + +### Building the Tool + +```bash +cd tools/cbt-creator +go build -o cbt scripts-go/cbt.go +``` + +### Creating Unencrypted CBT + +```bash +./cbt -input /path/to/images -output mycomic.cbt +``` + +**Example:** +```bash +./cbt -input ./comic-pages-folder -output "My Amazing Comic.cbt" +``` + +### Creating Encrypted CBT + +```bash +./cbt -input /path/to/images -output mycomic.cbt -password "your-password" +``` + +**Example:** +```bash +./cbt -input ./comic-pages-folder -output "Secret Comic.cbt" -password "super-secret-123" +``` + +### Program Options + +``` +Usage: cbt -input -output [-password ] + +Flags: + -input string + Input directory containing comic files + -output string + Output .cbt file + -password string + Password for encryption (leave empty for no encryption) +``` + +## Method 3: Manual Creation with TAR + +### Creating Unencrypted CBT + +```bash +cd /path/to/comic/images +tar -cf ../mycomic.cbt * +``` + +### Creating Encrypted CBT Manually + +1. **Create TAR archive:** + ```bash + tar -cf temp.tar * + ``` + +2. **Encrypt using OpenSSL:** + ```bash + # Generate key from password + KEY=$(echo -n "your-password" | sha256sum | cut -d' ' -f1) + + # Generate random IV + openssl rand -out iv.bin 16 + + # Encrypt + openssl enc -aes-256-cfb -K "$KEY" -iv $(xxd -p -c 256 iv.bin) -in temp.tar -out temp.enc + + # Combine IV and encrypted data + cat iv.bin temp.enc > mycomic.cbt + + # Cleanup + rm temp.tar iv.bin temp.enc + ``` + +## Directory Structure Best Practices + +### Recommended Structure + +``` +comic-pages/ +├── 001.jpg +├── 002.jpg +├── 003.jpg +├── ... +└── ComicInfo.xml +``` + +### File Naming + +Use zero-padded numbers for proper sorting: +- ✅ `001.jpg`, `002.jpg`, `003.jpg` +- ❌ `1.jpg`, `2.jpg`, `3.jpg` + +### Including ComicInfo.xml + +Always include metadata for best results: + +```xml + + + My Comic Title + My Series + 1 + Author Name + Artist Name + Publisher + Action, Adventure + 2024 + 24 + +``` + +## Automated Workflow Scripts + +### Batch Creation Script + +Create `batch-cbt.sh`: + +```bash +#!/bin/bash + +PASSWORD="your-default-password" + +for dir in */; do + dirname="${dir%/}" + echo "Processing: $dirname" + ./cbt.sh create -i "$dir" -o "${dirname}.cbt" -p "$PASSWORD" +done + +echo "Batch creation complete!" +``` + +Usage: +```bash +chmod +x batch-cbt.sh +./batch-cbt.sh +``` + +### Using with GPG-Encrypted Passwords + +Store passwords securely with GPG: + +```bash +#!/bin/bash + +# Store password encrypted +echo "my-secret-password" | gpg -e -r your@email.com > password.gpg + +# Use in script +PASSWORD=$(gpg -qd password.gpg) +./cbt.sh create -i ./comic -o comic.cbt -p "$PASSWORD" +``` + +## Testing Your CBT Files + +### Test with Gopherbook + +1. Upload to Gopherbook via web UI +2. Or place in watch folder: + ```bash + cp mycomic.cbt ./watch/[username]/ + ``` + +### Test Encryption + +```bash +# Should fail if encrypted +tar -tf mycomic.cbt + +# Should succeed if unencrypted +tar -tf mycomic.cbt +``` + +### Test Extraction + +```bash +./cbt.sh extract -i mycomic.cbt -o test-extract -p "password" +ls test-extract/ +``` + +## Integration with Comic Creation Tools + +### ImageMagick Conversion + +Convert PDF or images to comic pages: + +```bash +# Convert PDF to images +magick convert -density 300 comic.pdf page-%03d.jpg + +# Create CBT +./cbt.sh create -i . -o comic.cbt +``` + +### Optimize Images Before Packing + +```bash +# Optimize JPEGs +for img in *.jpg; do + mogrify -quality 85 -strip "$img" +done + +# Create optimized CBT +./cbt.sh create -i . -o optimized-comic.cbt -p "password" +``` + +## Troubleshooting + +### "Permission Denied" Error + +```bash +chmod +x scripts-bash/cbt.sh +``` + +### "Command Not Found" Errors + +Ensure required tools are installed: +```bash +# Ubuntu/Debian +sudo apt install tar openssl xxd coreutils + +# Fedora +sudo dnf install tar openssl vim-common coreutils + +# macOS +brew install gnu-tar openssl +``` + +### Encryption Issues + +Verify OpenSSL version: +```bash +openssl version +``` + +Should be OpenSSL 1.1.1 or higher. + +## Related Pages + +- [CBT File Format](CBT-Format) - Technical details +- [Bash Scripts](Bash-Scripts) - All available scripts +- [Password Protection](Password-Protection) - Security features + +--- + +**Tip**: Use the bash script for simplicity, or the Go program for cross-platform compatibility.