Chilkat.Jwt Class Overview

Chilkat.Jwt creates, parses, and verifies JSON Web Tokens. It supports HMAC-signed JWTs using shared secrets, RSA/ECC private-key signed JWTs, certificate-backed signing, header and payload decoding, NumericDate generation, and validation of common time-based claims such as exp and nbf.

What the Class Is Used For

Use Chilkat.Jwt when an application needs to create or verify compact JWT strings in the form xxxxx.yyyyy.zzzzz. The first part is the Base64Url encoded JOSE header, the second part is the Base64Url encoded claims payload, and the third part is the Base64Url encoded signature. The class provides separate methods for shared-secret HMAC JWTs and public/private-key JWTs.

Create HMAC JWTs Use CreateJwt for HS256, HS384, and HS512 tokens signed with a shared secret.
Create Private-Key JWTs Use CreateJwtPk or CreateJwtCert for RSA, RSA-PSS, and ECC signing algorithms.
Decode Token Parts Decode the JOSE header and claims payload without verifying the signature using GetHeader and GetPayload.
Verify Signatures and Time Claims Verify HMAC or public-key signatures, then validate exp and nbf timing with optional clock-skew leeway.

Typical JWT Creation Workflow

  1. Build the JOSE header JSON, or use a shorthand algorithm string such as HS256, RS256, or ES256.
  2. Build the claims payload JSON.
  3. Optionally call GenNumericDate to create NumericDate values for claims such as iat, nbf, or exp.
  4. For HMAC algorithms, call CreateJwt with the shared secret.
  5. For RSA/ECC/RSA-PSS algorithms, call CreateJwtPk with a PrivateKey, or CreateJwtCert with a certificate that has a private key.
  6. Use AutoCompact to control whether header and payload JSON are compacted before token creation.
  7. Check LastErrorText after failures or unexpected behavior.

Typical JWT Verification Workflow

  1. Receive a token in compact JWT form: xxxxx.yyyyy.zzzzz.
  2. Decode the header with GetHeader to inspect the JOSE alg.
  3. For HS256, HS384, or HS512, call VerifyJwt with the shared secret.
  4. For RSA or ECC algorithms, call VerifyJwtPk with the corresponding public key.
  5. Decode the claims payload with GetPayload after signature verification.
  6. Call IsTimeValid to validate exp and/or nbf claims, using a small leeway value when clock skew should be tolerated.

Core Concepts

Concept Meaning Important Members
Compact JWT Format A JWT is returned as three Base64Url-encoded parts separated by dots: header, payload, and signature. CreateJwt, CreateJwtPk, CreateJwtCert
JOSE Header JSON metadata describing the token, especially the signing algorithm in the alg field. GetHeader, CreateJwt, CreateJwtPk
Claims Payload JSON claims contained in the token, such as subject, issuer, expiration, or application-specific claims. GetPayload, IsTimeValid, GenNumericDate
HMAC-Signed JWT A JWT signed and verified with the same shared secret string. CreateJwt, VerifyJwt
Private-Key JWT A JWT signed with an RSA or ECC private key, or with a certificate that has a private key. CreateJwtPk, CreateJwtCert, VerifyJwtPk
NumericDate A JSON numeric value representing seconds since 1970-01-01T00:00:00Z, ignoring leap seconds. GenNumericDate

Core Properties

Property Purpose Guidance
AutoCompact Controls whether JSON passed to CreateJwt and CreateJwtPk is compacted to remove unnecessary whitespace. Default is true, which produces the smallest possible JWT.
UncommonOptions Catch-all property for uncommon needs. Defaults to the empty string and should typically remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Creating JWTs

Signing Method Use This Method Supported alg Values
Shared secret / HMAC CreateJwt HS256, HS384, HS512
RSA or ECC private key CreateJwtPk RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512
Certificate private key CreateJwtCert RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512
Header shorthand: Creation methods accept either the full JOSE JSON header or a shorthand algorithm string such as HS256, RS256, or ES256. Chilkat then uses the standard JOSE header for that algorithm.
RSA-PSS note: PS256, PS384, and PS512 support for JWT creation was added in Chilkat v10.0.0.

Verifying JWTs

Token Type Use This Method Key Material Supported alg Values
HMAC JWT VerifyJwt Shared password / secret string HS256, HS384, HS512
RSA or ECC JWT VerifyJwtPk PublicKey RS256, RS384, RS512, ES256, ES384, ES512
Algorithm safety rule: VerifyJwt immediately fails for non-HMAC algorithms, including none. VerifyJwtPk immediately fails for algorithms outside the RSA/ECC public-key family described by the method documentation.

Decoding Header and Payload

Need Method Behavior
Decode JOSE header GetHeader Decodes the first part of the JWT and returns the JOSE header JSON string.
Decode claims payload GetPayload Decodes the second part of the JWT and returns the claims payload JSON string.
Important: Decoding the header or payload is not the same as verifying the token. Verify the signature with VerifyJwt or VerifyJwtPk before trusting claims from an untrusted token.

Time-Based Claims

Task Method Behavior
Create NumericDate value GenNumericDate Generates seconds since 1970-01-01T00:00:00Z UTC for the current system time plus an offset in seconds. The offset may be negative.
Validate exp and/or nbf IsTimeValid Returns true when the current system date/time is within the allowed range defined by the token’s exp and/or nbf claims.
Allow clock skew IsTimeValid leeway argument The leeway is a number of seconds added to tolerate small clock differences, usually no more than a few minutes.

Algorithm Families

Family alg Values Create With Verify With
HMAC HS256, HS384, HS512 CreateJwt VerifyJwt
RSA PKCS#1 v1.5 RS256, RS384, RS512 CreateJwtPk or CreateJwtCert VerifyJwtPk
RSA-PSS PS256, PS384, PS512 CreateJwtPk or CreateJwtCert Not listed in the VerifyJwtPk method’s supported algorithm list in this reference text.
ECDSA ES256, ES384, ES512 CreateJwtPk or CreateJwtCert VerifyJwtPk

Method Summary by Category

Category Methods Purpose
Create JWT CreateJwt, CreateJwtPk, CreateJwtCert Create compact JWT strings using HMAC shared secrets, RSA/ECC private keys, or certificates with private keys.
Verify JWT VerifyJwt, VerifyJwtPk Verify the token signature using either a shared secret or public key.
Decode token parts GetHeader, GetPayload Decode and return the JOSE header JSON or claims payload JSON.
Time helpers GenNumericDate, IsTimeValid Generate NumericDate values and validate exp / nbf claim timing.

Diagnostics and Troubleshooting

Problem Area Member What to Check
JWT creation fails CreateJwt, CreateJwtPk, CreateJwtCert, LastErrorText Confirm the header JSON or shorthand algorithm is valid, the payload is valid JSON, and the key type matches the selected algorithm.
HMAC verification fails VerifyJwt Confirm the token uses HS256, HS384, or HS512, and that the shared secret matches the one used to sign.
Public-key verification fails VerifyJwtPk Confirm the token uses a supported RSA or ECC algorithm and that the public key corresponds to the private key used for signing.
Token appears readable but is not trusted GetHeader, GetPayload Remember that decoding a JWT is not verification. Verify the signature before trusting the claims.
Token is rejected as expired or not yet valid IsTimeValid Check exp and nbf claims and consider a small leeway for clock skew.
JWT is larger than expected AutoCompact Leave AutoCompact enabled so unnecessary JSON whitespace is removed before token creation.

Common Pitfalls

Pitfall Better Approach
Using CreateJwt for RSA or ECC algorithms. Use CreateJwt only for HS256, HS384, and HS512. Use CreateJwtPk or CreateJwtCert for RSA/ECC/RSA-PSS signing.
Using VerifyJwt for public-key JWTs. Use VerifyJwt for HMAC tokens and VerifyJwtPk for RSA/ECC public-key validation.
Trusting GetPayload output before verifying the signature. Decode for inspection, but verify the signature before trusting claims.
Accepting alg: none tokens. The verification methods fail for incompatible algorithms such as none. Always verify using the expected method and key.
Forgetting to validate exp and nbf. Signature verification proves integrity and key possession; use IsTimeValid to check token timing.
Using large clock-skew leeway values. Use only a small leeway, usually no more than a few minutes.

Best Practices

Recommendation Reason
Choose the create/verify method based on the JOSE alg. HMAC algorithms use shared secrets, while RSA/ECC algorithms use private and public keys.
Use full JOSE header JSON when additional header parameters are required. Shorthand algorithm strings are convenient, but full JSON gives complete control over the header.
Keep AutoCompact enabled for normal token creation. Compact JSON produces the smallest JWT representation.
Verify signatures before trusting decoded claims. JWT header and payload decoding does not prove authenticity or integrity.
Validate time claims after signature verification. IsTimeValid checks whether the current system time is within the token’s allowed range.
Use GenNumericDate for standard JWT time values. It produces the numeric seconds-since-epoch format used by JWT time claims.
Check LastErrorText after failures. It provides the most useful diagnostic detail for token creation, decoding, verification, and time-validation issues.

Summary

Chilkat.Jwt is the Chilkat class for creating, decoding, verifying, and time-validating compact JSON Web Tokens. It supports HMAC shared-secret JWTs, RSA and ECC public/private-key JWTs, certificate-backed signing, NumericDate generation, header and payload decoding, and validation of exp and nbf claims.

The most important practical guidance is to match the method to the token’s alg, verify the signature before trusting decoded claims, validate time-based claims separately, and keep AutoCompact enabled unless preserving JSON whitespace is specifically required.