Ecc Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require paragonie/ecc:^2
   

   Ensure ext-gmp is enabled in your PHP environment.

2. First Use Case: Key Generation Generate a secure key pair using secp256k1 (Bitcoin curve):

   use Mdanter\Ecc\EccFactory;
   
   $curve = EccFactory::getSecgCurves()->curve256k1();
   $keyPair = $curve->generator()->getKeyPair();
   

3. Where to Look First

   • Examples: Review the examples directory for practical use cases (ECDH, ECDSA, Schnorr).
   • Documentation: Focus on EccFactory, SecureCurveFactory, and SchnorrSigner for modern workflows.
   • Security Notes: Prioritize SecureCurveFactory or OpenSSL-backed operations for production.

Implementation Patterns

Key Generation and Management

• Secure Key Generation: Use SecureCurveFactory for default-secure curves (e.g., secp256k1, nistp256):

  $secureFactory = EccFactory::getSecureSecgCurves();
  $keyPair = $secureFactory->curve256k1()->generator()->getKeyPair();
  

  Store private keys in encrypted storage (e.g., Laravel’s encryption facade).

• Curve Selection: Prefer nistp256/nistp384 for general use or secp256k1 for Bitcoin compatibility. Avoid insecure curves (e.g., nistp192) unless explicitly allowed:

  $insecureFactory = EccFactory::getNistCurves(null, true); // Bypass security check
  

ECDH (Key Exchange)

• Shared Secret Calculation:

  $alicePrivateKey = ...; // From key pair
  $bobPublicKey = ...;     // From peer
  
  $ecdh = new \Mdanter\Ecc\Crypto\EcDH();
  $sharedSecret = $ecdh->calculateSharedSecret($alicePrivateKey, $bobPublicKey);
  

  Use openssl_derive() or HKDF to derive symmetric keys from the shared secret.

Signatures (ECDSA/Schnorr)

• ECDSA Signing/Verification:

  $signer = new \Mdanter\Ecc\Crypto\Signature\Signer();
  $signature = $signer->signWithKey($privateKey, $message);
  $valid = $signer->verifyWithKey($publicKey, $message, $signature);
  

  Critical: Use HMAC-DRBG for k generation to avoid bias:

  $rng = new \Mdanter\Ecc\Math\HmacDrbg();
  $keyPair = $curve->generator($rng)->getKeyPair();
  

• Schnorr Signatures (Modern Alternative):

  $schnorr = new \Mdanter\Ecc\Crypto\Signature\SchnorrSigner();
  $signature = $schnorr->signWithKey($privateKey, $message);
  $valid = $schnorr->verifyWithKey($publicKey, $message, $signature);
  

  Prefer Schnorr for new systems (forward secrecy, simpler verification).

Integration with Laravel

• Service Provider: Bind factories and utilities in AppServiceProvider:

  public function register()
  {
      $this->app->singleton('ecc.secureFactory', function () {
          return EccFactory::getSecureSecgCurves();
      });
  }
  

• Encrypted Storage: Serialize keys with serialize() or json_encode() and encrypt with Laravel’s Crypt:

  $encrypted = Crypt::encrypt($privateKey->getSecretScalar()->toString());
  

Gotchas and Tips

Pitfalls

1. Insecure Curves:

   • Default behavior blocks curves with <120-bit security (e.g., nistp192).
   • Fix: Use SecureCurveFactory or explicitly allow insecure curves with true flag.

2. Side-Channel Attacks:

   • Non-constant-time operations (e.g., generic ECC) may leak secrets.
   • Fix: Prefer OpenSSL-backed operations (PHP 8.1+) or optimized curves:

     $curve = EccFactory::getNistCurves()->optimizedCurve256();
     

3. Key Reuse:

   • Reusing k in ECDSA breaks security.
   • Fix: Use HMAC-DRBG for k generation (default in Signer).

4. OpenSSL Dependency:

   • OpenSSL 3.0+ (PHP 8.1+) provides constant-time operations.
   • Debugging: Disable OpenSSL for testing:

     $curve->disableOpenssl();
     

Debugging Tips

• Invalid Signatures:

  • Verify message hashing (use hash_hmac with SHA-256/384/512).
  • Check key serialization (ensure hex strings are correct length).

• Performance:

  • OpenSSL is ~10x faster than pure PHP. Enable it where possible.
  • Optimized curves (e.g., nistp256) have minimal overhead vs. generic ECC.

Extension Points

1. Custom Curves: Extend CurveFactory to add non-standard curves (e.g., Curve25519):

   class CustomCurveFactory extends CurveFactory {
       public function curve25519() { ... }
   }
   

2. Key Storage: Implement KeyInterface for custom key formats (e.g., PEM):

   class PemKey implements KeyInterface { ... }
   

3. Schnorr Hardening: Override SchnorrSigner to enforce stricter k generation:

   class StrictSchnorrSigner extends SchnorrSigner {
       protected function generateK() { ... }
   }
   

Laravel-Specific Quirks

• Caching Keys: Cache key pairs in Redis with a short TTL (e.g., 1 hour) to avoid regeneration:

  $key = Cache::remember('ecc-key-pair', 3600, function () {
      return $secureFactory->curve256k1()->generator()->getKeyPair();
  });
  

• Queue Jobs: Offload ECDH/Signature operations to queues to avoid blocking requests:

  Dispatch(new HandleEcdh($alicePrivateKey, $bobPublicKey))->onQueue('ecc');