Aes Key Wrap Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require spomky-labs/aes-key-wrap
   

   • No additional config needed; autoloads via Composer.

2. First Use Case: Wrapping a Key

   use SpomkyLabs\KeyWrap\KeyWrap;
   
   $keyWrap = new KeyWrap('my-secret-key-32bytes'); // Must be 32 bytes for AES-256
   $wrappedKey = $keyWrap->wrap('key-to-wrap-32bytes'); // Input must also be 32 bytes
   

3. First Use Case: Unwrapping a Key

   $unwrappedKey = $keyWrap->unwrap($wrappedKey);
   

4. Where to Look First

   • RFC3394 (default) and RFC5649 docs for algorithm specifics.
   • src/KeyWrap.php for core logic (minimal, ~100 lines).
   • Tests for edge cases (e.g., invalid key lengths).

Implementation Patterns

Core Workflows

1. Key Rotation

   • Wrap old keys with a new master key, then discard the old master.

   $masterKey = 'new-master-key-32bytes';
   $keyWrap = new KeyWrap($masterKey);
   $wrappedOldKey = $keyWrap->wrap($oldMasterKey);
   

2. Secure Storage

   • Store wrapped keys in a database or config (e.g., .env):

   $wrappedKey = base64_encode($keyWrap->wrap($sensitiveKey));
   config(['services.api.key' => $wrappedKey]);
   

   • Unwrap on demand:

   $keyWrap->unwrap(base64_decode(config('services.api.key')));
   

3. Integration with Laravel

   • Service Provider Binding:

     $this->app->singleton(KeyWrap::class, function ($app) {
         return new KeyWrap(config('services.master_key'));
     });
     

   • Encrypted Config:

     $wrapped = $this->app->make(KeyWrap::class)->wrap(config('app.encryption_key'));
     config(['app.encryption_key_wrapped' => $wrapped]);
     

4. Batch Operations

   • Wrap/unwrap multiple keys in a loop:

   $keys = ['key1', 'key2', 'key3'];
   $wrappedKeys = array_map([$keyWrap, 'wrap'], $keys);
   

Advanced Patterns

• Key Versioning Use wrapped keys to track versions (e.g., wrapped_key_v1, wrapped_key_v2).
• Hybrid Encryption Combine with defuse/php-encryption for asymmetric key exchange:

  $publicKey = ...;
  $sharedSecret = openssl_encrypt($masterKey, 'AES-256-CBC', $publicKey, ...);
  $keyWrap = new KeyWrap($sharedSecret);
  

Gotchas and Tips

Pitfalls

1. Key Length Requirements

   • Master Key: Must be 32 bytes (256 bits) for AES-256. Throws InvalidArgumentException otherwise.
   • Data Key: Must also be 32 bytes. Padding/truncation is not handled—validate inputs:

     if (strlen($key) !== 32) {
         throw new \InvalidArgumentException('Key must be 32 bytes.');
     }
     

2. RFC Compliance

   • Defaults to RFC3394 (AES-KWP). For RFC5649 (AES-KW), instantiate with:

     $keyWrap = new KeyWrap($masterKey, KeyWrap::RFC5649);
     

   • Output formats differ slightly; ensure recipient uses the same RFC.

3. Base64 Handling

   • Wrapped keys are binary; encode/decode manually:

     $wrapped = base64_encode($keyWrap->wrap($key)); // Store
     $keyWrap->unwrap(base64_decode($wrapped));      // Retrieve
     

4. Thread Safety

   • Stateless; safe for concurrent use (no shared state).

Debugging Tips

• Invalid Output? Verify:

  • Input keys are 32 bytes.
  • Correct RFC is used (RFC3394 vs. RFC5649).
  • No silent truncation/padding in upstream code.

• Performance Wrapping/unwrapping is O(1) but I/O (e.g., DB reads) may bottleneck. Cache wrapped keys if reused frequently.

Extension Points

1. Custom Key Derivation Pre-process keys with hash_hmac or sodium_crypto_kdf before wrapping:

   $derivedKey = hash_hmac('sha256', $key, $salt, true);
   $keyWrap->wrap($derivedKey);
   

2. Logging Wrap unwrap() in a try-catch to log failed decryption attempts (potential brute-force):

   try {
       $keyWrap->unwrap($wrappedKey);
   } catch (\Exception $e) {
       \Log::warning("Failed to unwrap key: {$e->getMessage()}");
   }
   

3. Testing Use the library’s test suite as a reference for edge cases (e.g., empty keys, non-ASCII data). Mock KeyWrap in unit tests:

   $mockWrap = $this->createMock(KeyWrap::class);
   $mockWrap->method('unwrap')->willReturn('unwrapped-key');