Eos Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require b3da/eos-bundle "dev-master"
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   B3da\EasyOpenSslBundle\B3daEasyOpenSslBundle::class => ['all' => true],
   

2. Configuration: Add to config/packages/eos.yaml (Symfony 4+) or config.yml (Symfony 3):

   eos_enc_method: aes-256-cbc  # Default encryption method
   

3. First Use Case: Inject the service in a controller or command:

   use B3da\EasyOpenSslBundle\Service\EasyOpenSslService;
   
   class MyController extends AbstractController {
       public function __construct(private EasyOpenSslService $eos) {}
   
       public function encryptMessage() {
           $client = new Client(); // Your custom Client entity
           $this->eos->generateKeyPairForClient($client);
           $encrypted = $this->eos->encrypt($client, 'Sensitive data');
           return new Response($encrypted);
       }
   }
   

Implementation Patterns

Core Workflows

1. Key Management:

   • Generate Key Pairs:

     $client = new Client();
     $this->eos->generateKeyPairForClient($client); // Auto-persists keys
     

   • Export/Import Public Keys:

     $publicKey = $this->eos->exportPublicKey($client);
     $this->eos->importPublicKey($anotherClient, $publicKey);
     

2. Encryption/Decryption:

   • Encrypt with Private Key (sender):

     $encrypted = $this->eos->encrypt($senderClient, 'Secret message');
     

   • Decrypt with Public Key (recipient):

     $decrypted = $this->eos->decrypt($encrypted, $recipientClient);
     

3. API Integration (Optional): Enable routes in config/routes.yaml:

   b3da_easy_open_ssl:
       resource: "@B3daEasyOpenSslBundle/Resources/config/routing.yml"
       prefix: /api/eos
   

   Use endpoints for:

   • /api/eos/client/create (POST)
   • /api/eos/msg/encrypt/{clientId}/{data} (GET)

Integration Tips

• Custom Entities: Extend B3da\EasyOpenSslBundle\Entity\Client and Message to store keys/messages in your DB schema.
• Dependency Injection: Prefer constructor injection for EasyOpenSslService in controllers/commands.
• Error Handling: Check return values (e.g., generateKeyPairForClient returns false on failure).
• Symfony Forms: Bind encrypted data to form fields using DataTransformer:

  $form->add('encryptedData', TextType::class, [
      'transformer' => new EncryptionTransformer($this->eos)
  ]);
  

Gotchas and Tips

Common Pitfalls

1. Key Persistence:

   • The bundle does not auto-persist keys by default. Ensure your Client entity has @ORM\Column for publicKey/privateKey fields.
   • Fix: Add flush() after generateKeyPairForClient():

     $this->eos->generateKeyPairForClient($client);
     $this->entityManager->flush();
     

2. Encryption Method:

   • Default (aes-256-cbc) may not suit all use cases. Override in config:

     eos_enc_method: aes-128-gcm  # Requires OpenSSL 1.0.1+
     

   • Tip: Validate the method exists in openssl_get_cipher_methods() before use.

3. API Endpoints:

   • Endpoints like /encrypt/{data} do not validate input length. Large payloads may cause timeouts.
   • Workaround: Use POST requests with JSON bodies for large data.

4. Key Rotation:

   • The bundle lacks built-in key rotation. Implement a rotateKeys() method in your Client entity:

     public function rotateKeys(EasyOpenSslService $eos) {
         $eos->generateKeyPairForClient($this);
         $this->oldPublicKey = $this->publicKey; // Backup old key
     }
     

Debugging Tips

1. OpenSSL Errors:

   • Wrap operations in try-catch:

     try {
         $this->eos->encrypt($client, 'data');
     } catch (\RuntimeException $e) {
         // Log OpenSSL errors (e.g., "error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt")
     }
     

   • Fix: Ensure openssl.cipher-sections is enabled in php.ini.

2. Key Format Issues:

   • Public/private keys must be PEM-encoded. Validate with:

     if (!openssl_pkey_get_public($client->publicKey)) {
         throw new \RuntimeException('Invalid public key format');
     }
     

3. Performance:

   • Encryption/decryption is CPU-intensive. Cache keys in memory (e.g., Redis) for repeated use:

     $cacheKey = 'eos:keys:' . $client->id;
     $keys = $this->cache->get($cacheKey);
     if (!$keys) {
         $keys = $this->eos->getKeys($client);
         $this->cache->set($cacheKey, $keys, 3600);
     }
     

Extension Points

1. Custom Ciphers:

   • Extend B3da\EasyOpenSslBundle\Service\EasyOpenSslService to add methods like:

     public function signData(Client $client, string $data): string {
         return base64_encode(openssl_sign($data, $signature, $client->privateKey));
     }
     

2. Event Listeners:

   • Hook into key generation:

     // config/services.yaml
     B3da\EasyOpenSslBundle\EventListener\KeyGenerationListener:
         tags:
             - { name: kernel.event_listener, event: eos.key_generated, method: onKeyGenerated }
     

3. Doctrine Lifecycle Callbacks:

   • Auto-generate keys when a Client is persisted:

     use B3da\EasyOpenSslBundle\Service\EasyOpenSslService;
     
     class Client {
         public function __construct(private EasyOpenSslService $eos) {}
     
         public function prePersist() {
             $this->eos->generateKeyPairForClient($this);
         }
     }