Jwt Encryption Algorithm Aeskw Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require web-token/jwt-encryption-algorithm-aeskw
   

2. Basic Usage Import the algorithm and use it with a JWT library (e.g., firebase/php-jwt or lucadegasperi/oauth2-server):

   use WebToken\JWT\Signature\Algorithm\AESKW;
   
   // Initialize the algorithm with a key (must be 256-bit for AES-256-KW)
   $algorithm = new AESKW('your-256-bit-secret-key-here');
   
   // Use with a JWT library (example with firebase/php-jwt)
   $jwt = JWT::encode($payload, null, [$algorithm]);
   

3. First Use Case Encrypt a JWT payload for secure storage/transmission where the recipient has the same key:

   $payload = ['user_id' => 123, 'exp' => time() + 3600];
   $token = JWT::encode($payload, null, [$algorithm]);
   

Implementation Patterns

Key Management

• Key Storage: Store keys securely (e.g., Laravel’s config, environment variables, or a dedicated secrets manager like AWS KMS).
• Key Rotation: Implement a rotation strategy by maintaining multiple keys and updating the AESKW instance dynamically.

  // Example: Rotate keys periodically
  $currentKey = config('jwt.aeskw_key');
  $algorithm = new AESKW($currentKey);
  

Integration with Laravel

1. Service Provider Bind the algorithm to Laravel’s container for reuse:

   // app/Providers/JWTServiceProvider.php
   public function register()
   {
       $this->app->singleton(AESKW::class, function ($app) {
           return new AESKW(config('jwt.aeskw_key'));
       });
   }
   

2. Middleware for JWT Validation Use the algorithm in middleware to decrypt and validate tokens:

   // app/Http/Middleware/ValidateJWT.php
   public function handle($request, Closure $next)
   {
       $token = $request->bearerToken();
       $algorithm = app(AESKW::class);
       $decoded = JWT::decode($token, null, [$algorithm]);
       // Proceed with authenticated request
   }
   

Workflow: Encrypt/Decrypt Tokens

1. Encrypt (Issue Token)

   $algorithm = app(AESKW::class);
   $token = JWT::encode($payload, null, [$algorithm]);
   

2. Decrypt (Validate Token)

   try {
       $decoded = JWT::decode($token, null, [$algorithm]);
   } catch (Exception $e) {
       // Handle invalid token
   }
   

Gotchas and Tips

Pitfalls

1. Key Length Requirement

   • The key must be exactly 256 bits (32 bytes) for AES-256-KW. Shorter keys will throw exceptions.
   • Fix: Generate a key using OpenSSL:

     openssl rand -hex 32
     

2. Algorithm Compatibility

   • Ensure your JWT library supports custom algorithms. Some libraries (e.g., firebase/php-jwt) require explicit registration:

     JWT::setAlgorithmMethod('AESKW', [$algorithm]);
     

3. Performance Overhead

   • AES-KW is slower than symmetric algorithms (e.g., HMAC). Benchmark in your use case if latency is critical.

Debugging

• Invalid Token Errors

  • Verify the key matches exactly (case-sensitive, no extra whitespace).
  • Check token payload structure (e.g., exp claims must be valid).

• Logging Enable JWT library logging to debug decryption failures:

  JWT::setLogger(new Monolog\Logger('jwt'));
  

Extension Points

1. Custom Key Derivation Extend the algorithm to derive keys from passwords using PBKDF2:

   use WebToken\JWT\Signature\Algorithm\AESKW;
   use function Sodium\crypto_pwhash;
   
   $key = crypto_pwhash('str', 'password', ['algo' => SODIUM_CRYPTO_PWHASH_ALG_DEFAULT]);
   $algorithm = new AESKW($key);
   

2. Hybrid Encryption Combine with RSA for asymmetric key exchange (e.g., encrypt the AES key with RSA, then use AES-KW for the JWT):

   // Pseudocode
   $aesKey = openssl_random_pseudo_bytes(32);
   $rsaEncryptedKey = openssl_public_encrypt($aesKey, $encrypted, $publicKey);
   $algorithm = new AESKW($aesKey);
   

3. Laravel Configuration Centralize key management in config/jwt.php:

   'aeskw' => [
       'key' => env('JWT_AESKW_KEY'),
       'enabled' => env('JWT_AESKW_ENABLED', false),
   ],