Signing (JWS)
Sign and verify JWTs with HMAC, RSA, and EC keys.
A JSON Web Signature (JWS) is a JWT whose payload has been signed — anyone with the verification key can confirm the token was issued by the holder of the signing key and that the claims have not been tampered with.
This guide walks through the three signing families that bx-jwt supports:
HMAC (HS256, HS384, HS512) — symmetric, one key signs and verifies
RSA (RS256, RS384, RS512) — asymmetric, private signs / public verifies
EC (ES256, ES384, ES512) — asymmetric, smaller keys than RSA
HMAC
HMAC is the simplest option: a single shared secret signs and verifies the token. Use it when both ends of the conversation are services you control.
// Generate an RFC 7518–compliant 256-bit secret
secret = jwtGenerateSecret( 256 );
token = jwtCreate( { sub: "user-123", iss: "my-api" }, secret, "HS256" );
payload = jwtVerify( token, secret, "HS256" );RSA
RSA gives you asymmetric signing: a private key issues tokens, a public key verifies them. Distribute the public key freely — give the private key only to the issuer.
keys = jwtGenerateKeyPair( "RS256" ); // 2048-bit RSA pair
token = jwtCreate( { sub: "user-123" }, keys.privateKey, "RS256" );
payload = jwtVerify( token, keys.publicKey, "RS256" );For long-lived production keys, persist the PEM strings to disk or to a secret manager and reference them through the key registry.
EC (Elliptic Curve)
EC signing produces dramatically smaller signatures and key material than RSA at equivalent security levels.
Verifying with Claim Assertions
Pass a claims struct to jwtVerify() to enforce expected values:
A mismatch throws bxjwt.JWTVerificationException.
Verify vs Validate vs Decode
Refreshing Tokens
Use jwtRefresh() to re-issue an existing token with fresh iat, jti, and an optional new exp. All application claims are preserved.
Related
Last updated
Was this helpful?
