Crypto Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add the package via Composer:

     composer require dterranova/crypto-bundle:dev-master
     

   • Register the bundle in AppKernel.php:

     new dterranova\Bundle\CryptoBundle\dterranovaCryptoBundle(),
     

   • Configure the bundle in config.yml:

     dterranova_crypto:
         temp_folder: "%kernel.root_dir%/../web/temp_crypto"
         chunk_file_size: 2  # in Mb
     

2. First Use Case: Encrypt a file in a controller or service:

   use Symfony\Component\HttpFoundation\Response;
   
   public function encryptAction($filePath, $key)
   {
       $crypto = $this->get('dterranova_crypto.crypto_adapter');
       $encryptedFolder = $crypto->encryptFile($filePath, $key);
       return new Response("File encrypted in: $encryptedFolder");
   }
   

Implementation Patterns

Core Workflows

1. Chunked Encryption/Decryption:

   • Encrypt large files by splitting them into configurable chunks (default: 2MB).
   • Useful for memory efficiency when handling files > RAM capacity.
   • Example:

     // Encrypt a 100MB file without loading it entirely into memory
     $crypto->encryptFile('/path/to/large_file.pdf', 'secure_key_123');
     

2. Service Integration:

   • Inject dterranova_crypto.crypto_adapter into services for reusable encryption logic.
   • Example in a custom service:

     class FileProcessor
     {
         protected $crypto;
     
         public function __construct($crypto)
         {
             $this->crypto = $crypto;
         }
     
         public function processFile($filePath, $key)
         {
             $encryptedPath = $this->crypto->encryptFile($filePath, $key);
             // Process encrypted file (e.g., upload to cloud)
         }
     }
     

3. Decryption Workflow:

   • Decrypt by referencing the original filename (not the encrypted chunks).
   • Example:

     $originalFilePath = '/path/to/original_file.pdf';
     $crypto->decryptFile($originalFilePath, 'secure_key_123');
     

Integration Tips

• File Storage:

  • Store encrypted chunk folders in a dedicated directory (e.g., storage/encrypted/).
  • Use Symfony’s Filesystem component to manage paths dynamically:

    $tempFolder = $this->getParameter('dterranova_crypto.temp_folder');
    

• Key Management:

  • Store encryption keys securely (e.g., environment variables or Symfony’s ParameterBag).
  • Avoid hardcoding keys in configuration files.

• Event-Driven Processing:

  • Trigger post-encryption/decryption events (e.g., delete original file, notify users).
  • Example with Symfony Events:

    $dispatcher->dispatch(new FileEncryptedEvent($encryptedFolder));
    

Gotchas and Tips

Pitfalls

1. Temp Folder Permissions:

   • Ensure the temp_folder is writable by the web server user.
   • Debugging: Check storage/logs/ for Permission denied errors.

2. Chunk Size Trade-offs:

   • Too Small: High I/O overhead (many small files).
   • Too Large: Memory spikes during encryption.
   • Default chunk_file_size: 2 is reasonable for most use cases.

3. Filename Collisions:

   • If two files have the same name, encrypted chunks will overwrite each other.
   • Fix: Append a UUID to filenames or use unique paths:

     $uniqueKey = uniqid();
     $crypto->encryptFile("/path/to/file_$uniqueKey.pdf", $key);
     

4. Key Rotation:

   • Re-encrypt files if keys are rotated (no built-in support; implement manually).

Debugging

• Verify Encryption:

  • Compare file sizes before/after encryption (encrypted files should be larger).
  • Use file_exists() to check if chunk folders are created:

    $encryptedFolder = $crypto->encryptFile($filePath, $key);
    var_dump(file_exists($encryptedFolder)); // Should return true
    

• Memory Usage:

  • Monitor memory with memory_get_usage() during encryption of large files.
  • Adjust chunk_file_size if memory limits are hit.

Extension Points

1. Custom Chunk Handlers:

   • Override chunk processing by extending the bundle’s CryptoAdapter class.
   • Example:

     class CustomCryptoAdapter extends \dterranova\Bundle\CryptoBundle\Service\CryptoAdapter
     {
         protected function processChunk($chunk, $key) {
             // Custom logic (e.g., compression before encryption)
             return parent::processChunk($chunk, $key);
         }
     }
     

2. Post-Processing Hooks:

   • Use Symfony’s KernelEvents::TERMINATE to clean up temp folders after decryption:

     $event->getKernel()->getContainer()->get('dterranova_crypto.crypto_adapter')->cleanupTempFiles();
     

3. Logging:

   • Enable debug logging in config.yml:

     monolog:
         handlers:
             main:
                 level: debug
     

   • Check logs for chunking progress or errors.

Configuration Quirks

• Path Formatting:

  • Ensure temp_folder uses absolute paths (relative paths may fail in production).
  • Example:

    temp_folder: "%kernel.project_dir%/var/encrypted_chunks"
    

• Environment-Specific Settings:

  • Override chunk_file_size per environment (e.g., smaller chunks in CI):

    # config_dev.yml
    dterranova_crypto:
        chunk_file_size: 0.5  # For testing