RUEN
Package · jwt

Algorithms

Every algorithm Flytachi JWT supports, the key material each expects, and how JWK key types map onto them. This is the authoritative list — other pages link here.

Supported algorithms

Nine algorithms across three families. The value in the alg header must be one of these, or encode()/decode() throws “Algorithm ‘…’ is not supported.”

alg Family Mechanism Hash Key material
HS256 HMAC hash_hmac SHA-256 shared secret string
HS384 HMAC hash_hmac SHA-384 shared secret string
HS512 HMAC hash_hmac SHA-512 shared secret string
RS256 RSA openssl_sign SHA-256 RSA key pair
RS384 RSA openssl_sign SHA-384 RSA key pair
RS512 RSA openssl_sign SHA-512 RSA key pair
ES256 ECDSA openssl_sign SHA-256 EC key pair (P-256)
ES384 ECDSA openssl_sign SHA-384 EC key pair (P-384)
ES512 ECDSA openssl_sign SHA-512 EC key pair (P-521)

Symmetric vs asymmetric

HMAC (HS*) RSA / ECDSA (RS* / ES*)
Sign key shared secret private key
Verify key same shared secret public key
Key selection on decode by kid, else the single key supplied the same
kid needed when there are several keys when there are several keys
Who can forge anyone with the secret only the private-key holder

The algorithm is pinned to the key

Both PrivateKey and PublicKey carry their algorithm. On decode, the verifying key’s algorithm must equal the token header’s alg — a mismatch is rejected before verification. See the Security model.

The ECDSA signature format

Worth knowing if you compare tokens byte by byte or debug interoperability: ES* carry the signature as a raw pair of numbers, R || S, each left-padded with zeros to the width of the curve (RFC 7515 §3.4). There is no ASN.1 wrapper in the token, even though openssl_sign() returns one.

alg Curve Signature length
ES256 P-256 64 bytes (32 + 32)
ES384 P-384 96 bytes (48 + 48)
ES512 P-521 132 bytes (66 + 66)

The library converts in both directions itself. The tell-tale sign of an implementation that does not is a signature beginning with 0x30: a DER structure that went into the token as-is, which no third-party verifier will accept.

JWK key types

The JWK parser accepts the three standard kty values and maps them to the families above:

kty Required JWK fields Verifies Curve field
RSA n, e, alg RS* —
EC crv, x, y, alg ES* crv (below)
oct k, alg HS* —

EC curve mapping

JWK crv Algorithm Coordinate size
P-256 ES256 32 bytes
P-384 ES384 48 bytes
P-521 ES512 66 bytes

Any other curve throws “Unsupported EC curve”. See Verifying with JWKS for parsing key sets.

Generating keys per family

bash
# HMAC — a random shared secret
openssl rand -base64 32

# RSA — a 2048-bit key pair
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

# ECDSA (ES256) — a P-256 key pair
openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem
openssl ec -in ec-private.pem -pubout -out ec-public.pem

For ES384 use -name secp384r1; for ES512 use -name secp521r1.