RUEN
Package · jwt

Installation & Requirements

Flytachi JWT has a tiny footprint — two standard PHP extensions and nothing else. This page covers the requirements and how to produce the keys you’ll sign with.

System requirements

  • PHP version — 8.1 or higher.
  • Operating system — any. There are no POSIX dependencies, so Linux, macOS, BSD, and Windows all work.
  • PHP extensions
    • ext-openssl — signing/verifying RSA and ECDSA tokens, and converting JWKS keys to usable public keys.
    • ext-json — encoding and decoding the token’s header and payload segments.

Check installed extensions with php -m.

bash
composer require flytachi/jwt

No extra runtime dependencies

The library requires only ext-openssl and ext-json — both ship with virtually every PHP build. The JWKS parser builds PEM keys in pure PHP, so there’s nothing else to install.

Choosing an algorithm

Which keys you need depends on the algorithm family. See the algorithms reference for the full matrix.

Family Key type When to use
HMAC (HS*) one shared secret string Same party signs and verifies (your own API).
RSA (RS*) private + public key pair You sign; others verify with your public key.
ECDSA (ES*) private + public key pair Same as RSA, with smaller keys and signatures.

HMAC: just a secret

For HS256/HS384/HS512 there are no files to generate — you need a single strong secret string, shared by signer and verifier. Generate one with:

bash
# 32 random bytes, base64-encoded
openssl rand -base64 32

Keep the secret secret

With HMAC the same key both signs and verifies. Anyone who has it can mint valid tokens — store it like a password (environment variable, secrets manager), never in source control.

RSA: generate a key pair

bash
# Private key (used to sign)
openssl genrsa -out private.pem 2048

# Public key (used to verify) — derive it from the private key
openssl rsa -in private.pem -pubout -out public.pem

Load them in PHP with OpenSSL:

php
use Flytachi\Jwt\Entity\PrivateKey;
use Flytachi\Jwt\Entity\PublicKey;

$signingKey = new PrivateKey(
  openssl_pkey_get_private(file_get_contents('private.pem')),
  'RS256',
  'my-key-id' // kid — required so decode() can find the matching public key
);

$verifyKey = new PublicKey(
  openssl_pkey_get_public(file_get_contents('public.pem')),
  'RS256'
);

ECDSA: generate a key pair

ECDSA uses named curves — P-256 for ES256, P-384 for ES384, P-521 for ES512:

bash
# ES256 uses the prime256v1 (P-256) curve
openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem
openssl ec -in ec-private.pem -pubout -out ec-public.pem

Loading is identical to RSA — pass the OpenSSL key object and the matching algorithm (ES256). See the asymmetric keys guide for full sign/verify examples.

Never commit private keys

private.pem and ec-private.pem sign tokens on your behalf. Add them to .gitignore and load them from a secure path or secret store at runtime.

Next steps