Download the PHP package omegaalfa/jwtoken without Composer

JwToken

JwToken is a production-ready PHP library for signing, validating and rotating JSON Web Tokens (JWTs) while keeping strict claim checks and clear error handling.

✅ Security audited – Zero critical/high vulnerabilities | RFC 7519 compliant | Resistant to common JWT attacks

What's New in version

• ✅ Enhanced security: All 15 vulnerabilities fixed, achieving A+ (9.8/10) rating
• ✅ Stricter validations: iat, nbf, exp validated during token creation
• ✅ Kid format enforcement: kid must match /^[a-zA-Z0-9_-]{1,64}$/
• ✅ jti length validation: Between 16-128 characters (prevents brute-force)
• ✅ Reduced clock skew: Maximum reduced from 300s to 60s for better security
• ✅ Timestamp protection: MAX_TIMESTAMP_OFFSET prevents tokens older than 10 years
• ✅ Consistent error messages: Generic errors prevent information disclosure
• ✅ API improvements: Use setExpectedIssuer(), setExpectedAudience(), setClockSkew() methods

Why use JwToken?

Supported Algorithms

HMAC (Symmetric):

• HS256 - HMAC with SHA-256 (requires ≥32 byte secret)
• HS384 - HMAC with SHA-384 (requires ≥48 byte secret)
• HS512 - HMAC with SHA-512 (requires ≥64 byte secret)

RSA (Asymmetric):

• RS256 - RSA with SHA-256 (requires ≥2048 bit keys, recommended)
• RS384 - RSA with SHA-384 (requires ≥2048 bit keys, higher security)
• RS512 - RSA with SHA-512 (requires ≥2048 bit keys, maximum security)

Installation

HS256 quick start

The following snippet creates a token and validates it against issuer and audience hints.

Claim-driven validation template

Reuse this pattern in controllers or middlewares when decoding user tokens:

Claim reference

Temporal Claim Validation

JwToken validates temporal claims both during token creation and validation:

During createToken():

• iat (issued-at): Must be a positive integer not exceeding current time + 10 years
• nbf (not-before): Must be a positive integer not exceeding current time + 10 years
• exp (expiration): Must be a positive integer not exceeding current time + 10 years
• nbf cannot be greater than exp when both are present

During validateToken():

• exp: Token is rejected if current time > exp (with clock skew tolerance)
• nbf: Token is rejected if current time < nbf (with clock skew tolerance)
• iat: Validated if present (with clock skew tolerance)

This dual validation prevents creation of tokens with unrealistic timestamps and ensures runtime validation respects clock drift.

HMAC key rotation with kid

Maintaining multiple HMAC secrets lets you rotate without invalidating traffic immediately.

Key ID (kid) Validation

The kid (Key ID) claim is strictly validated:

• Format: Must match /^[a-zA-Z0-9_-]{1,64}$/ (alphanumeric, underscore, hyphen only)
• Length: Between 1 and 64 characters
• Validation: Occurs during both token creation and validation
• Security: Prevents path traversal and injection attacks via malicious kid values

If a header lacks a valid kid, the constructor secret acts as fallback so legacy clients still work.

RSA usage (RS256, RS384, RS512)

When you need public/private key pairs, provide the PEM files and let JwToken verify signatures with OpenSSL. JwToken supports three RSA signature algorithms:

• RS256 - RSA with SHA-256 (most common)
• RS384 - RSA with SHA-384 (higher security)
• RS512 - RSA with SHA-512 (maximum security)

Ensure your .pem files use at least 2048-bit RSA keys stored outside the document root (e.g. storage/keys or a protected volume).

RSA rotation workflow

1. Generate a new key pair and register it with setRsaKeyPaths.
2. Start signing new tokens with the fresh key and include its kid.
3. Keep the old key registered until its tokens expire.
4. Remove the old kid entry and (optionally) rotate the default pathPublicKey once telemetry shows zero usage.

Revocation and jti

Every token receives a jti (JWT ID) when none is supplied. The jti must be a string between 16 and 128 characters for security reasons. Pair jti with a revocation store to explicitly invalidate tokens:

jti Validation Rules

• Type: Must be a string
• Length: Between 16 and 128 characters
• Auto-generation: If not provided, generates a 32-character base64url string
• Security: Short jti values are rejected to prevent brute-force attacks

Use a persistent store (Redis, database) in production. Always revoke a token immediately when you suspect credential theft.

Security audit & compliance

This library has undergone comprehensive security analysis and achieved an A+ security rating (9.8/10):

Verified protections against:

• ✅ alg=none bypass attack
• ✅ Key confusion attacks (HMAC/RSA)
• ✅ Timing attacks (constant-time comparison)
• ✅ Token forgery & signature stripping
• ✅ Algorithm downgrade attacks
• ✅ Replay attacks (temporal validation)
• ✅ Token substitution (iss/aud enforcement)
• ✅ Base64 encoding manipulation
• ✅ JSON injection
• ✅ DoS via oversized tokens

Last audit: December 2025 | Vulnerabilities found: 0 Critical, 0 High, 0 Medium

📖 Security Documentation:

• SECURITY_CERTIFICATE.md - Official A+ (9.8/10) security certificate
• SECURITY_BEST_PRACTICES.md - Complete deployment guide
• SECURITY.md - Vulnerability reporting policy

Security best practices

• Keep secrets and RSA keys in your vault/secret manager rather than source control.
• Pair short-lived access tokens (5–15 minutes) with refresh tokens that you rotate securely.
• Explicitly set expectedIssuer and expectedAudience for every consumer.
• Favor HS512 or RS256; fallback only when compatibility demands it.
• Monitor jwt.validateToken() failures to detect tampering or clock skew issues.
• Log and alert on revocation decisions tied to jti.
• See the security policy for the preferred way to report vulnerabilities and what branches remain supported.

Built-in security protections

This library implements multiple layers of defense against common JWT attacks:

Configuring clock skew safely

Token age limits

Tokens with iat (issued-at) timestamps older than 10 years are automatically rejected to prevent abuse of long-lived tokens. This limit is enforced by the MAX_TIMESTAMP_OFFSET constant (315,360,000 seconds = 10 years).

JwToken

JwToken is a PHP library for creating, signing and validating JSON Web Tokens (JWT) with support for:

• HMAC (HS256, HS384, HS512)
• RSA (RS256)
• Temporal claims (exp, nbf, iat) and contextual claims (iss, aud)

• jti (JWT ID) with optional integration for revocation

  Important: this library is designed for production use. Make sure to read the “Security best practices” section before integrating.

  Installation

  Via Composer:

Quick start (HS256)

The most common setup is HS256 with a secret stored in an environment variable:

Requirements

• PHP: 8.4+
• Extension: ext-openssl

Concepts and features

• HMAC algorithms (HS256/384/512) via hash_hmac, with internal mapping to sha256, sha384, sha512.
• RS256 via openssl_sign / openssl_verify, using private/public key files.
• Supported claims:
  • exp – expiration time, validated automatically.
  • nbf – not-before, rejects tokens used before the configured time.
  • iat – issued-at, can be used with configurable clock skew.
  • iss – issuer, compared against expectedIssuer.
  • aud – audience, compared against expectedAudience.
  • jti – JWT ID, generated automatically if missing and used with RevocationStoreInterface.
• Additional protections:
  • Maximum token length limit.
  • Safe parsing (3 segments, strict Base64/JSON decoding).
  • Constant-time comparison for HMAC signatures via hash_equals (timing attack protection).

Basic usage with HMAC (HS256)

HMAC key rotation with setHmacKeys and kid

To make HMAC key rotation easier, you can register multiple secrets and use the kid header:

If the header does not contain kid or the kid is not found in setHmacKeys, the library falls back to the secretKey provided in the constructor.

Usage with RS256 (public/private key)

Make sure your RSA keys have at least 2048 bits and are stored outside the public document root (e.g. storage/keys or a secure volume mounted in your container).

RSA key rotation with setRsaKeyPaths and kid

Just like with HMAC, you can register multiple RSA key pairs and select which one to use via kid:

If the kid provided does not exist in setRsaKeyPaths, the library falls back to the default pathPrivateKey/pathPublicKey.

Practical RSA rotation strategy

A common key rotation strategy:

1. Introduce a new key: generate a new key pair (k2) and configure it in setRsaKeyPaths, while keeping the old key (k1) for validation.
2. Start signing with k2: in all places that issue tokens, use ['kid' => 'k2'] in createToken(). Legacy tokens signed with k1 remain valid because k1 is still configured.
3. Monitor k1 usage: use logs/telemetry to track when the volume of tokens using the old key becomes negligible.
4. Decommission k1: remove k1 entries from setRsaKeyPaths (and/or update the default pathPublicKey) so that tokens signed with the old key are no longer accepted.

This flow allows for gradual rotation without locking out users, while keeping strict validation of alg and kid.

Revocation and jti

All generated tokens receive a jti (unique JWT ID) when the payload does not provide one:

• If you configure revocationStore with an implementation of RevocationStoreInterface, you can revoke specific tokens.

Simple in-memory example (for tests only):

✅ Setter Methods (REQUIRED)

Other Breaking Changes

1. Clock Skew Maximum: Reduced from 300s to 60s
2. jti Validation: Must be 16-128 characters (was any length)
3. kid Format: Must match /^[a-zA-Z0-9_-]{1,64}$/ (was any string)
4. Timestamp Validation: iat, nbf, exp now validated during createToken()
5. Error Messages: Now generic to prevent information disclosure

Migration Checklist

• [ ] Replace all property assignments with setter methods
• [ ] Review clock skew values (max is now 60s)
• [ ] Validate kid format in existing tokens
• [ ] Ensure jti values are 16-128 characters
• [ ] Test temporal claims (iat, nbf, exp) are within 10-year limit
• [ ] Update error handling for generic validation messages

Recommended environment configuration (php.ini)