omnizip 0.3.1

data/docs/getting-started/your-first-archive.adoc

@@ -0,0 +1,218 @@
+---
+title: Your First Archive
+nav_order: 4
+parent: Getting Started
+---
+
+== Your First Archive
+
+=== General
+
+This guide walks you through creating your first archive with Omnizip, covering both .7z and ZIP formats.
+
+=== Creating a Simple 7z Archive
+
+==== Command Line
+
+[source,bash]
+----
+# Create a 7z archive with default settings
+omnizip archive create backup.7z document.txt photo.jpg
+----
+
+This creates a new archive using LZMA2 compression at level 5 (default).
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Create archive with default settings
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z')
+writer.add_file('document.txt')
+writer.add_file('photo.jpg')
+writer.close
+
+puts "Archive created successfully!"
+----
+
+=== Customizing Compression
+
+==== Higher Compression
+
+[source,bash]
+----
+omnizip archive create backup.7z documents/ \
+  --algorithm lzma2 --level 9
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 9
+)
+writer.add_directory('documents/')
+writer.close
+----
+
+==== Faster Compression
+
+[source,bash]
+----
+omnizip archive create backup.7z data/ \
+  --algorithm lzma2 --level 1
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 1
+)
+writer.add_directory('data/')
+writer.close
+----
+
+=== Creating a ZIP Archive
+
+==== Command Line
+
+[source,bash]
+----
+# Create a ZIP archive
+omnizip archive create backup.zip documents/ \
+  --format zip
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+writer = Omnizip::Formats::Zip::Writer.new('backup.zip')
+writer.add_directory('documents/')
+writer.close
+----
+
+=== Using Filters for Executables
+
+BCJ filters improve compression of executable files:
+
+[source,bash]
+----
+omnizip archive create binaries.7z app.exe \
+  --filters bcj_x86
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('binaries.7z',
+  filters: [:bcj_x86]
+)
+writer.add_file('app.exe')
+writer.close
+----
+
+=== Creating Multi-Volume Archives
+
+Split large archives into multiple volumes:
+
+[source,bash]
+----
+# Create volumes of 100MB each
+omnizip archive create backup.7z.001 large_data/ \
+  --volume-size 100M
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z.001',
+  volume_size: 100 * 1024 * 1024
+)
+writer.add_directory('large_data/')
+writer.close
+----
+
+=== Encrypting Archives
+
+Protect your archives with a password:
+
+[source,bash]
+----
+omnizip archive create secure.7z documents/ \
+  --password "MySecurePassword123!"
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('secure.7z',
+  password: 'MySecurePassword123!'
+)
+writer.add_directory('documents/')
+writer.close
+----
+
+=== Complete Example
+
+Here's a complete example that creates a backup archive:
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Create encrypted backup with high compression
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 7,
+  password: ENV['BACKUP_PASSWORD'],
+  solid: true
+)
+
+# Add directories
+writer.add_directory('/home/user/documents')
+writer.add_directory('/home/user/projects')
+writer.add_directory('/home/user/photos')
+
+# Write the archive
+writer.close
+
+# Get statistics
+info = Omnizip::Formats::SevenZip::Reader.info('backup.7z')
+puts "Archive created:"
+puts "  Files: #{info.entry_count}"
+puts "  Size: #{info.uncompressed_size} bytes"
+puts "  Compressed: #{info.compressed_size} bytes"
+puts "  Ratio: #{(info.compressed_size.to_f / info.uncompressed_size * 100).round(1)}%"
+----
+
+=== Verifying Your Archive
+
+Always verify your archive after creation:
+
+[source,bash]
+----
+omnizip archive list backup.7z
+----
+
+[source,ruby]
+----
+require 'omnizip'
+
+reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
+reader.open
+puts "Archive contents:"
+reader.each_file do |entry|
+  puts "  #{entry.name} (#{entry.size} bytes)"
+end
+reader.close
+----
+
+=== Next Steps
+
+* link:../guides/basic-usage/creating-archives[Creating Archives Guide] - More archive options
+* link:../guides/advanced-usage/solid-compression[Solid Archives] - Better compression for similar files
+* link:../guides/advanced-usage/encryption[Encryption Guide] - Password protection details
+* link:../guides/basic-usage/extracting-archives[Extracting Archives] - How to extract your archives

data/docs/guides/advanced-features/encryption.adoc

@@ -0,0 +1,300 @@
+---
+title: Encryption
+nav_order: 4
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+Protect sensitive data in your archives with industry-standard AES-256 encryption. Omnizip supports multiple encryption methods across different archive formats.
+
+== Benefits
+
+* **Strong Security**: AES-256 encryption with secure key derivation
+* **Format Flexibility**: Encryption available in both ZIP and 7z formats
+* **Header Protection**: Encrypt filenames and metadata (7z format)
+* **Password Validation**: Built-in password strength checking
+* **Compatibility**: Works with archives from other tools
+
+== Encryption Methods
+
+=== AES-256 (7z Format)
+
+The strongest encryption option with header protection:
+
+[source,ruby]
+----
+# Create encrypted 7z archive
+Omnizip::Archive.create(
+  'secure.7z',
+  format: :seven_zip,
+  password: 'MyStr0ngP@ssw0rd',
+  encrypt_headers: true  # Hide filenames
+) do |archive|
+  archive.add_file('confidential.pdf', 'documents/confidential.pdf')
+  archive.add_directory('sensitive_data/')
+end
+----
+
+**Features**:
+
+* AES-256-CBC encryption
+* PBKDF2-HMAC-SHA256 key derivation (524,288 iterations)
+* Optional header encryption (hides filenames)
+* HMAC-SHA-256 authentication
+
+=== WinZip AES (ZIP Format)
+
+Industry-standard AES encryption for ZIP archives:
+
+[source,ruby]
+----
+# Create AES-encrypted ZIP
+Omnizip::Zip::File.open('secure.zip', create: true) do |zip|
+  zip.password = 'SecurePassword123'
+  zip.encryption = :winzip_aes  # AES-256
+  zip.add('private.doc', 'files/private.doc')
+end
+----
+
+**Features**:
+
+* AES-256, AES-192, or AES-128
+* Compatible with WinZip, 7-Zip, PeaZip
+* HMAC-SHA-1 authentication
+* Standard ZIP format
+
+=== Traditional ZIP Encryption
+
+[WARNING]
+Traditional ZIP encryption (ZipCrypto) is weak and should only be used for compatibility with legacy systems.
+
+[source,ruby]
+----
+# Only for compatibility - NOT RECOMMENDED
+Omnizip::Zip::File.open('legacy.zip', create: true) do |zip|
+  zip.password = 'password'
+  zip.encryption = :traditional  # Weak encryption
+  zip.add('file.txt', 'data.txt')
+end
+----
+
+== Decrypting Archives
+
+=== Provide Password at Open
+
+[source,ruby]
+----
+# Decrypt 7z archive
+Omnizip::Archive.open('secure.7z', password: 'MyStr0ngP@ssw0rd') do |archive|
+  archive.extract_all('decrypted/')
+end
+
+# Decrypt ZIP archive
+Omnizip::Zip::File.open('secure.zip', password: 'SecurePassword123') do |zip|
+  zip.extract_all('output/')
+end
+----
+
+=== Password via Environment Variable
+
+[source,ruby]
+----
+# Set password in environment
+ENV['OMNIZIP_PASSWORD'] = 'MyStr0ngP@ssw0rd'
+
+# Opens without explicit password parameter
+Omnizip::Archive.open('secure.7z') do |archive|
+  archive.extract_all('output/')
+end
+----
+
+== Password Management
+
+=== Password Strength Validation
+
+Ensure strong passwords before encryption:
+
+[source,ruby]
+----
+validator = Omnizip::PasswordValidator.new(
+  min_length: 12,
+  require_uppercase: true,
+  require_lowercase: true,
+  require_numbers: true,
+  require_special: true
+)
+
+begin
+  validator.validate('weak')
+rescue Omnizip::WeakPasswordError => e
+  puts "Password too weak: #{e.message}"
+  # Password must be at least 12 characters with uppercase, lowercase, numbers, and special characters
+end
+
+# Use validated password
+validator.validate('MyStr0ng!P@ssw0rd2024')  # ✅ Passes
+----
+
+=== Secure Password Input
+
+Prompt for passwords without echo:
+
+[source,ruby]
+----
+require 'io/console'
+
+def get_password
+  print "Enter password: "
+  password = STDIN.noecho(&:gets).chomp
+  puts # New line after password entry
+  password
+end
+
+password = get_password
+Omnizip::Archive.create('secure.7z', password: password) do |archive|
+  # Create encrypted archive
+end
+----
+
+== Security Best Practices
+
+. **Use Strong Passwords**: Minimum 12 characters with mixed case, numbers, and symbols
+. **Prefer 7z Format**: Header encryption hides filenames and structure
+. **Avoid Traditional Encryption**: Use WinZip AES or 7z AES-256 instead
+. **Secure Password Storage**: Never hardcode passwords in source code
+. **Key Derivation**: Use default iterations (524,288) or higher
+. **Test Decryption**: Always verify encrypted archives can be decrypted
+
+== Encryption Comparison
+
+[cols="2,1,1,1,1"]
+|===
+|Feature |7z AES-256 |WinZip AES |Traditional |Recommendation
+
+|**Security Level**
+|Excellent
+|Very Good
+|Weak
+|Use 7z or WinZip AES
+
+|**Header Encryption**
+|✅
+|❌
+|❌
+|7z for privacy
+
+|**Key Derivation**
+|PBKDF2-SHA256
+|PBKDF2-SHA1
+|CRC check
+|Modern algorithms
+
+|**Authentication**
+|HMAC-SHA-256
+|HMAC-SHA-1
+|None
+|Detects tampering
+
+|**Compatibility**
+|7-Zip, PeaZip
+|Most tools
+|Universal
+|Consider audience
+|===
+
+== Command-Line Usage
+
+[source,bash]
+----
+# Create encrypted archive
+omnizip archive create secure.7z files/ \
+  --password 'MyStr0ngP@ssw0rd' \
+  --encrypt-headers
+
+# Extract with password
+omnizip archive extract secure.7z output/ \
+  --password 'MyStr0ngP@ssw0rd'
+
+# Or prompt for password
+omnizip archive create secure.7z files/ --password
+Enter password: ********
+----
+
+== Common Use Cases
+
+=== Protect Sensitive Documents
+
+[source,ruby]
+----
+# Encrypt sensitive files before cloud storage
+Omnizip::Archive.create(
+  'confidential-docs.7z',
+  format: :seven_zip,
+  password: secure_password,
+  encrypt_headers: true,
+  compression: :lzma2,
+  level: 9
+) do |archive|
+  archive.add_directory('contracts/')
+  archive.add_directory('financial-records/')
+end
+
+# Upload to cloud storage
+cloud_storage.upload('confidential-docs.7z')
+----
+
+=== Secure Backups
+
+[source,ruby]
+----
+# Create encrypted backup with timestamp
+timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+backup_file = "backup_#{timestamp}.7z"
+
+Omnizip::Archive.create(
+  backup_file,
+  format: :seven_zip,
+  password: ENV['BACKUP_PASSWORD'],
+  encrypt_headers: true
+) do |archive|
+  archive.add_directory('/var/www/app/')
+  archive.add_directory('/etc/app-config/')
+end
+----
+
+== Troubleshooting
+
+=== Wrong Password Error
+
+[source,ruby]
+----
+begin
+  Omnizip::Archive.open('secure.7z', password: 'wrong') do |archive|
+    archive.extract_all('output/')
+  end
+rescue Omnizip::DecryptionError => e
+  puts "Incorrect password: #{e.message}"
+end
+----
+
+=== Unsupported Encryption Method
+
+Some older archives may use unsupported encryption:
+
+[source,ruby]
+----
+begin
+  Omnizip::Archive.open('old-archive.zip') do |archive|
+    # ...
+  end
+rescue Omnizip::UnsupportedEncryptionError => e
+  puts "Encryption method not supported: #{e.message}"
+  puts "Try opening with 7-Zip or WinZip first"
+end
+----
+
+== See Also
+
+* link:../../compatibility.html[Compatibility] - Encryption support across formats

data/docs/guides/advanced-features/index.adoc

@@ -0,0 +1,49 @@
+---
+title: Advanced Features
+nav_order: 30
+parent: Guides
+has_children: true
+---
+
+== Advanced Features Overview
+
+Omnizip provides several advanced features for power users and production deployments.
+
+== Available Features
+
+[cols="1,3"]
+|===
+|Feature |Description
+
+|link:streaming.html[Streaming Operations]
+|Process archives without loading entire files into memory
+
+|link:parallel-processing.html[Parallel Processing]
+|Leverage multiple CPU cores for faster compression
+
+|link:progress-tracking.html[Progress Tracking]
+|Real-time progress monitoring for long operations
+
+|link:encryption.html[Encryption]
+|AES-256 password protection for archives
+|===
+
+== Feature Combinations
+
+These features can be combined for maximum efficiency:
+
+[source,ruby]
+----
+# Combine streaming + parallel + progress
+Omnizip.compress_directory('large_data/', 'backup.7z',
+  parallel: true,
+  threads: 8
+) do |progress|
+  puts "#{progress.percentage}% - #{progress.throughput_mb_s} MB/s"
+end
+----
+
+== See Also
+
+* link:../compression-algorithms/[Compression Algorithms] - Algorithm-specific features
+* link:../performance-tuning.html[Performance Tuning] - Optimize for your workload