Jwt Signature Algorithm Rsa Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require web-token/jwt-signature-algorithm-rsa
   

   Ensure your project uses firebase/php-jwt (v5+ recommended) as the base JWT library.

2. First Use Case Generate an RSA-signed JWT token:

   use Firebase\JWT\JWT;
   use WebToken\Signature\Algorithm\Rsa\Rsa;
   
   $key = file_get_contents('path/to/private.key');
   $token = JWT::encode(
       ['user_id' => 123],
       $key,
       'RS256', // Algorithm identifier
       null,
       ['alg' => 'RS256', 'key_id' => 'my-key-id']
   );
   

3. Where to Look First

   • Source Code (if available)
   • tests/ directory for usage examples.
   • Check composer.json for dependencies and version constraints.

Implementation Patterns

Core Workflow

1. Key Management

   • Store private keys securely (e.g., environment variables, AWS KMS, or Laravel's config).
   • Example:

     $privateKey = config('jwt.private_key');
     $token = JWT::encode($payload, $privateKey, 'RS256');
     

2. Algorithm Selection

   • Use RS256 for production (SHA-256 + RSA).
   • Use RS512 for larger payloads (SHA-512 + RSA).
   • Avoid RS384 unless explicitly required.

3. Verification

   $publicKey = file_get_contents('path/to/public.key');
   $decoded = JWT::decode($token, $publicKey, ['RS256']);
   

4. Laravel Integration

   • Extend Laravel's JWTGuard or Tymon\JWTAuth:

     // In AuthServiceProvider
     $this->app['auth']->extend('jwt', function ($app) {
         return new JWTGuard(
             new JWT($app['config']['jwt.key'], 'RS256')
         );
     });
     

5. Batch Processing

   • For bulk token generation/validation, use array_map with the JWT methods.

Gotchas and Tips

Pitfalls

1. Key Format

   • Ensure keys are in PEM format (begin with -----BEGIN RSA PRIVATE KEY-----).
   • OpenSSL-generated keys may need conversion:

     openssl rsa -in key.pem -outform PEM -out key_converted.pem
     

2. Algorithm Mismatch

   • Always verify the alg claim matches the key type (e.g., RS256 for RSA).
   • Attackers may use weak algorithms like HS256; enforce RS* in your app.

3. Key Size

   • Use 2048-bit or 4096-bit RSA keys. Avoid 1024-bit (vulnerable to brute force).

4. Clock Skew

   • If using nbf (not before) or exp (expiry), account for server clock drift:

     $now = time();
     $token = JWT::encode($payload, $key, 'RS256', $now - 300); // Allow 5-min skew
     

Debugging

1. Invalid Signature

   • Verify the key path, permissions (chmod 600), and format.
   • Test with OpenSSL:

     openssl rsautl -verify -in token.raw -pubin -inkey public.key -sign
     

2. Decoding Failures

   • Check for malformed tokens (use JWT::decode() without a key to inspect claims).
   • Validate the kid (key ID) claim if using multiple keys.

3. Performance

   • RSA signing is slower than HMAC. Cache tokens where possible (e.g., Redis).

Extension Points

1. Custom Key Resolvers

   • Override key resolution for dynamic keys:

     $keyResolver = function ($keyId) {
         return file_get_contents("keys/{$keyId}.pem");
     };
     JWT::decode($token, $keyResolver, ['RS256']);
     

2. Algorithm Switching

   • For backward compatibility, support multiple algorithms:

     $supportedAlgs = ['RS256', 'RS512', 'HS256'];
     JWT::decode($token, $key, $supportedAlgs);
     

3. Laravel Service Provider

   • Bind the package to Laravel's container:

     $this->app->bind('jwt.rsa', function () {
         return new Rsa();
     });