final corrections
parent
10efd45fd8
commit
cd311d7955
SSH key fingerprint:
SHA256:dP5B5iLpXU5V8aBA8eGm9tN5YtxXJybnv4McyltPyzM
2 changed files with 521 additions and 0 deletions
189
CBT-Format.md
Normal file
189
CBT-Format.md
Normal file
|
|
@ -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
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<ComicInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
||||
<Title>The Amazing Adventure</Title>
|
||||
<Series>Super Comics</Series>
|
||||
<Number>42</Number>
|
||||
<Writer>John Doe</Writer>
|
||||
<Artist>Jane Smith</Artist>
|
||||
<Publisher>Comic Press</Publisher>
|
||||
<Genre>Action, Adventure</Genre>
|
||||
<Tags>superhero, action</Tags>
|
||||
<StoryArc>The Grand Quest</StoryArc>
|
||||
<Year>2024</Year>
|
||||
<Month>1</Month>
|
||||
<Summary>An epic tale of heroism...</Summary>
|
||||
<PageCount>24</PageCount>
|
||||
</ComicInfo>
|
||||
```
|
||||
|
||||
## 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.
|
||||
332
Creating-CBT-Files.md
Normal file
332
Creating-CBT-Files.md
Normal file
|
|
@ -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 <input_directory> -o <output_file> [-p <password>]
|
||||
Extract: cbt.sh extract -i <input_file> -o <output_directory> [-p <password>]
|
||||
|
||||
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 <directory> -output <file.cbt> [-password <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
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<ComicInfo>
|
||||
<Title>My Comic Title</Title>
|
||||
<Series>My Series</Series>
|
||||
<Number>1</Number>
|
||||
<Writer>Author Name</Writer>
|
||||
<Artist>Artist Name</Artist>
|
||||
<Publisher>Publisher</Publisher>
|
||||
<Genre>Action, Adventure</Genre>
|
||||
<Year>2024</Year>
|
||||
<PageCount>24</PageCount>
|
||||
</ComicInfo>
|
||||
```
|
||||
|
||||
## 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue