Easy Ecc Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require paragonie/easy-ecc
   

   Add to composer.json under require:

   "paragonie/easy-ecc": "^1.3"
   

2. First Use Case: Generate a Curve25519 keypair and sign a message:

   use ParagonIE\EasyECC\EasyECC;
   
   $ecc = new EasyECC(); // Defaults to Curve25519
   $privateKey = $ecc->generatePrivateKey();
   $publicKey = $privateKey->getPublicKey();
   
   $message = "Hello, Easy-ECC!";
   $signature = $ecc->sign($message, $privateKey);
   
   // Verify
   $isValid = $ecc->verify($message, $publicKey, $signature);
   

3. Where to Look First:

   • README.md for core usage.
   • ECDSA-Specific Features for PEM serialization.
   • Asymmetric Encryption for Defuse integration.

Implementation Patterns

Core Workflows

1. Key Generation & Management:

   $ecc = new EasyECC('P256'); // NIST P-256
   $privateKey = $ecc->generatePrivateKey();
   $publicKey = $privateKey->getPublicKey();
   
   // Serialize for storage
   $pemPrivate = $privateKey->exportPem();
   $compressedPublic = $publicKey->toString();
   

2. Signing & Verification:

   $signature = $ecc->sign($message, $privateKey, true); // IEEE-P1363 format
   $isValid = $ecc->verify($message, $publicKey, $signature, true);
   

3. Key Exchange (ECDH):

   $bobPrivate = $ecc->generatePrivateKey();
   $bobPublic = $bobPrivate->getPublicKey();
   
   $sharedSecretAlice = $ecc->keyExchange($privateKey, $bobPublic, true);
   $sharedSecretBob = $ecc->keyExchange($bobPrivate, $publicKey, false);
   

4. Asymmetric Encryption (Defuse Integration):

   $defuse = new \ParagonIE\EasyECC\Integration\Defuse($ecc);
   $encrypted = $defuse->asymmetricEncrypt($data, $privateKey, $bobPublic);
   $decrypted = $defuse->asymmetricDecrypt($encrypted, $bobPrivate, $publicKey);
   

Laravel-Specific Patterns

1. Service Provider Binding:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(EasyECC::class, function () {
           return new EasyECC('P256'); // Configure default curve
       });
   }
   

2. Key Storage in Database:

   // Model: User.php
   protected $casts = [
       'private_key_pem' => 'encrypted',
       'public_key_compressed' => 'string',
   ];
   
   public function generateKeys()
   {
       $ecc = app(EasyECC::class);
       $privateKey = $ecc->generatePrivateKey();
       $this->private_key_pem = $privateKey->exportPem();
       $this->public_key_compressed = $privateKey->getPublicKey()->toString();
       $this->save();
   }
   

3. Middleware for Signed Requests:

   // app/Http/Middleware/VerifySignature.php
   public function handle($request, Closure $next)
   {
       $ecc = app(EasyECC::class);
       $publicKey = app('public_key_repository')->get($request->user());
       $isValid = $ecc->verify($request->getContent(), $publicKey, $request->signature);
   
       if (!$isValid) {
           abort(403, 'Invalid signature');
       }
   
       return $next($request);
   }
   

4. Encrypted Attributes:

   // Model: EncryptedModel.php
   use ParagonIE\EasyECC\Integration\Defuse;
   
   protected $appends = ['encrypted_data'];
   protected $defuse;
   
   public function __construct()
   {
       $this->defuse = new Defuse(app(EasyECC::class));
   }
   
   public function getEncryptedDataAttribute()
   {
       return $this->defuse->unseal($this->attributes['encrypted_data'], $this->privateKey);
   }
   
   public function setEncryptedDataAttribute($value)
   {
       $this->attributes['encrypted_data'] = $this->defuse->seal($value, $this->publicKey);
   }
   

Gotchas and Tips

Pitfalls

1. Curve Mismatch:

   • Decoding a compressed public key with the wrong curve throws an exception.
   • Fix: Always ensure the curve used for serialization matches the EasyECC instance.

2. Signature Format Confusion:

   • sign()/verify() methods accept a boolean for IEEE-P1363 format (default: false for PEM).
   • Tip: Use true for ECDSA signatures requiring IEEE-P1363 (e.g., interoperability with other systems).

3. Key Exchange Direction:

   • The keyExchange() method’s third argument ($isAlice) determines the shared secret derivation.
   • Gotcha: Swapping $isAlice between parties will yield different results.
   • Fix: Always pass true for the initiator and false for the responder.

4. Defuse Integration Quirks:

   • Requires defuse/php-encryption (composer require defuse/php-encryption).
   • Tip: Use seal()/unseal() for anonymous encryption (no shared key needed).

5. PHP 8.4+ Deprecations:

   • Updated to support PHP 8.4 via paragonie/ecc v2.5.0.
   • Tip: Test with PHP 8.4 in CI if targeting modern environments.

Debugging Tips

1. Key Validation:

   try {
       $publicKey = $ecc->importPublicKey($compressedKey);
   } catch (\ParagonIE\EasyECC\EasyECCException $e) {
       // Handle invalid key (wrong curve, malformed, etc.)
   }
   

2. Signature Verification:

   • Use var_dump($signature) to check format (PEM vs. IEEE-P1363).
   • Tip: For ECDSA, PEM signatures are base64-encoded, while IEEE-P1363 are binary.

3. Shared Secret Debugging:

   $aliceSecret = $ecc->keyExchange($alicePrivate, $bobPublic, true);
   $bobSecret = $ecc->keyExchange($bobPrivate, $alicePublic, false);
   var_dump(bin2hex($aliceSecret), bin2hex($bobSecret)); // Should match
   

Extension Points

1. Custom Encryption Backend: Implement ParagonIE\EasyECC\EncryptionInterface for non-Defuse symmetric encryption:

   class CustomEncryption implements EncryptionInterface {
       public function seal($plaintext, PublicKeyInterface $publicKey): string { ... }
       public function unseal($ciphertext, PrivateKeyInterface $privateKey): string { ... }
       public function asymmetricEncrypt($plaintext, PrivateKeyInterface $privateKey, PublicKeyInterface $publicKey): string { ... }
       public function asymmetricDecrypt($ciphertext, PrivateKeyInterface $privateKey, PublicKeyInterface $publicKey): string { ... }
   }
   

2. Key Storage Abstraction: Create a repository to abstract key storage (e.g., database, Redis):

   class KeyRepository {
       public function storePrivateKey(PrivateKeyInterface $key, string $userId): void { ... }
       public function retrievePublicKey(string $userId): PublicKeyInterface { ... }
   }
   

3. Event Dispatching: Trigger events for key generation/signing (e.g., Laravel Events):

   event(new KeyGenerated($privateKey, $publicKey));
   

Performance Tips

1. Curve Selection:

   • Curve25519: Fastest for key exchange (default).
   • NIST P-256: Slower but widely compatible for ECDSA.

2. Caching:

   • Cache EasyECC instance in Laravel’s container (singleton).
   • Cache public keys if frequently reused (e.g., API clients).

3. Batch Operations: