mirror of
https://github.com/anotherhadi/jwt-tui.git
synced 2026-06-26 01:02:33 +02:00
Hadi
124 lines
3.9 KiB
Markdown
124 lines
3.9 KiB
Markdown
# JWT Reference
|
|
|
|
## Structure
|
|
|
|
A JSON Web Token is three Base64URL-encoded parts joined by dots:
|
|
|
|
```
|
|
header.payload.signature
|
|
```
|
|
|
|
- **Header**: algorithm and token type
|
|
- **Payload**: claims (statements about an entity)
|
|
- **Signature**: HMAC or RSA/ECDSA over header + payload
|
|
|
|
The header and payload are readable by anyone. JWTs are _signed_, not _encrypted_.
|
|
Use JWE if you need confidentiality.
|
|
|
|
## Header
|
|
|
|
```json
|
|
{
|
|
"alg": "HS256",
|
|
"typ": "JWT"
|
|
}
|
|
```
|
|
|
|
Common header parameters:
|
|
|
|
| Param | Description |
|
|
| ----- | ------------------------------------------ |
|
|
| `alg` | Signing algorithm (`HS256`, `RS256`, etc.) |
|
|
| `typ` | Token type: always `JWT` |
|
|
| `kid` | Key ID: hint for which key to use |
|
|
| `cty` | Content type: used for nested JWTs |
|
|
|
|
## Payload (Claims)
|
|
|
|
**Registered claims** (all optional, but recommended):
|
|
|
|
| Claim | Type | Description |
|
|
| ----- | ------ | --------------------------------------- |
|
|
| `iss` | string | Issuer: who created the token |
|
|
| `sub` | string | Subject: principal the token is about |
|
|
| `aud` | string | Audience: intended recipient(s) |
|
|
| `exp` | number | Expiration time (Unix timestamp) |
|
|
| `nbf` | number | Not before: token valid after this time |
|
|
| `iat` | number | Issued at (Unix timestamp) |
|
|
| `jti` | string | JWT ID: unique identifier |
|
|
|
|
**Private claims** are any additional fields agreed upon by the parties.
|
|
|
|
## Algorithms
|
|
|
|
| Algorithm | Type | Key type |
|
|
| --------- | -------------- | ------------------------- |
|
|
| `HS256` | HMAC + SHA-256 | Shared secret |
|
|
| `HS384` | HMAC + SHA-384 | Shared secret |
|
|
| `HS512` | HMAC + SHA-512 | Shared secret |
|
|
| `RS256` | RSA + SHA-256 | RSA key pair |
|
|
| `RS384` | RSA + SHA-384 | RSA key pair |
|
|
| `RS512` | RSA + SHA-512 | RSA key pair |
|
|
| `ES256` | ECDSA + P-256 | EC key pair |
|
|
| `ES384` | ECDSA + P-384 | EC key pair |
|
|
| `ES512` | ECDSA + P-521 | EC key pair |
|
|
| `none` | No signature | ⚠ Never use in production |
|
|
|
|
> This tool supports **HS256**, **HS384**, and **HS512**.
|
|
|
|
## Signature Computation
|
|
|
|
For HMAC algorithms:
|
|
|
|
```
|
|
signature = HMAC-SHA256(
|
|
base64url(header) + "." + base64url(payload),
|
|
secret
|
|
)
|
|
```
|
|
|
|
The final token:
|
|
|
|
```
|
|
base64url(header) + "." + base64url(payload) + "." + base64url(signature)
|
|
```
|
|
|
|
## Security
|
|
|
|
- **Never use `alg: none`**: disables signature verification entirely.
|
|
- Use **long, random secrets**: at least 256 bits (32 bytes) for HS256.
|
|
- Always validate **`exp`** (expiration) and **`nbf`** (not before).
|
|
- Validate **`iss`** and **`aud`** to prevent token reuse across services.
|
|
- The payload is **base64-encoded, not encrypted**: never store passwords or PII.
|
|
- Prefer **asymmetric algorithms** (RS256, ES256) for public-facing APIs.
|
|
- Store secrets in environment variables or a secrets manager, never in code.
|
|
|
|
## Brute-forcing a JWT Secret
|
|
|
|
If a token is signed with a weak HMAC secret, it can be recovered offline.
|
|
Both **hashcat** and **john** accept the raw JWT string as input:
|
|
|
|
```bash
|
|
# hashcat mode 16500 targets JWT (HS256/384/512)
|
|
hashcat -a 0 -m 16500 <token> wordlist.txt
|
|
|
|
# john the ripper
|
|
john --format=HMAC-SHA256 --wordlist=wordlist.txt jwt.txt
|
|
```
|
|
|
|
This only works against **HS\*** algorithms where the secret is a simple password or passphrase.
|
|
|
|
## Configuration
|
|
|
|
jwt-tui looks for a config file at `~/.config/jwt-tui/config.yaml`.
|
|
If the file does not exist the built-in defaults are used automatically.
|
|
|
|
To get a starting point you can edit, run:
|
|
|
|
```
|
|
jwt-tui --add-default-config
|
|
```
|
|
|
|
This writes the default config to `~/.config/jwt-tui/config.yaml` (or to the path given with `--config`).
|
|
You can then open that file in any text editor and change the values you want.
|