JSON Web Key (JWK)
| id | schema-atoms/rfc/rfc-7517 |
| authors | M. Jones |
| created | 2026-05-24 |
JSON Web Key (JWK)
RFC 7517 — Standards Track
Published: May 2015
Author: M. Jones
Suite: JOSE (JSON Object Signing and Encryption)
Abstract
RFC 7517 defines the JSON Web Key (JWK) data structure — a JSON object representation of a cryptographic key. It is part of the JOSE suite alongside RFC 7515 (JWS), RFC 7516 (JWE), and RFC 7518 (JWA). A JWK Set is a JSON object containing an array of JWKs, enabling parties to publish multiple keys under a single document.
1. Introduction
Cryptographic operations require keys to be described, stored, and exchanged in an interoperable format. JWK provides a JSON-native representation for RSA, EC, and symmetric keys that integrates with the rest of the JOSE suite. The format is designed for use in:
- JWS (RFC 7515) — to convey the public key that verifies a signature.
- JWE (RFC 7516) — to convey the key used to encrypt a content encryption key.
- OIDC and OAuth 2.0 — to publish server signing keys at a well-known JWKS endpoint.
2. Terminology
| Term | Meaning |
|---|---|
| JWK | JSON Web Key — a single JSON object representing one cryptographic key |
| JWK Set | A JSON object with a keys array containing one or more JWKs |
| JOSE | JSON Object Signing and Encryption — the RFC 75xx suite |
| Base64url | URL-safe base64 encoding without padding (RFC 4648 §5) |
| Base64urlUInt | Base64url encoding of an unsigned big-endian integer |
| kty | Key Type — the cryptographic algorithm family of a JWK |
3. JSON Web Key (JWK) Format
A JWK is a JSON object. All member names within a single JWK MUST be unique. The following common parameters are defined for all key types:
| Parameter | Req? | Description |
|---|---|---|
kty |
REQUIRED | Key Type: "RSA", "EC", or "oct". Identifies the algorithm family. |
use |
OPTIONAL | Public Key Use: "sig" (signature) or "enc" (encryption). |
key_ops |
OPTIONAL | Key Operations: array of permitted operations (see §4). |
alg |
OPTIONAL | Algorithm: intended algorithm from the JWA registry (RFC 7518). |
kid |
OPTIONAL | Key ID: unique identifier string for this key. |
x5u |
OPTIONAL | X.509 URL: URI pointing to an X.509 certificate or chain. |
x5c |
OPTIONAL | X.509 Certificate Chain: array of base64-encoded DER certificates. |
x5t |
OPTIONAL | X.509 SHA-1 Thumbprint: base64url SHA-1 of the DER certificate. |
x5t#S256 |
OPTIONAL | X.509 SHA-256 Thumbprint: base64url SHA-256 of the DER certificate. |
The use and key_ops parameters SHOULD NOT both be present in the same JWK; they convey overlapping information.
4. Key Operations (key_ops Values)
| Value | Meaning |
|---|---|
sign |
Compute a digital signature |
verify |
Verify a digital signature |
encrypt |
Encrypt content |
decrypt |
Decrypt content |
wrapKey |
Encrypt a key |
unwrapKey |
Decrypt a key |
deriveKey |
Derive a key |
deriveBits |
Derive bits not used as a key |
5. JWK Set Format
A JWK Set is a JSON object with the following REQUIRED member:
{
"keys": [
{ "kty": "EC", "kid": "1", "crv": "P-256", "x": "<base64url>", "y": "<base64url>" },
{ "kty": "RSA", "kid": "2", "n": "<base64url>", "e": "AQAB" }
]
}
Additional members MAY appear in a JWK Set and MUST be ignored by implementations that do not understand them. The kid of each key in the set SHOULD be unique within the set to support unambiguous key selection.
6. Key Type Parameters
6.1 RSA Keys (kty = "RSA")
All RSA parameter values use Base64urlUInt encoding: big-endian unsigned integer, base64url-encoded, no padding.
| Parameter | Required | Description |
|---|---|---|
n |
Public | RSA modulus |
e |
Public | RSA public exponent |
d |
Private | RSA private exponent |
p |
Optional private | First prime factor |
q |
Optional private | Second prime factor |
dp |
Optional private | First factor CRT exponent |
dq |
Optional private | Second factor CRT exponent |
qi |
Optional private | First CRT coefficient |
A private RSA JWK MUST include n, e, and d. Including p, q, dp, dq, and qi enables CRT-optimized RSA operations and is RECOMMENDED when the full private key is available.
6.2 Elliptic Curve Keys (kty = "EC")
EC coordinates are base64url-encoded and zero-padded to the full field element size for the curve.
| Parameter | Required | Description |
|---|---|---|
crv |
Yes | Curve: "P-256", "P-384", or "P-521" |
x |
Yes | x coordinate of the public key point |
y |
Yes | y coordinate of the public key point |
d |
Private only | EC private key scalar |
6.3 Symmetric Keys (kty = "oct")
| Parameter | Required | Description |
|---|---|---|
k |
Yes | Base64url-encoded raw key bytes (no padding) |
The key size is implicit in the length of the decoded byte sequence.
7. Encoding
- RSA key parameters (
n,e,d,p,q,dp,dq,qi): Base64urlUInt — the minimum-length big-endian unsigned integer representation, base64url-encoded without padding. - EC coordinates (
x,y,d): base64url of the fixed-size byte array for the curve, left-padded with zeros to the required length. - Symmetric keys (
k): base64url of the raw key bytes. - No base64 padding characters (
=) appear in any JWK value.
8. Security Considerations
Key confidentiality. Private key parameters (d, p, q, dp, dq, qi for RSA; d for EC; k for oct) MUST be kept confidential. Any endpoint serving private JWKs MUST require authentication and SHOULD use TLS.
Key confusion attacks. Applications that accept JWKs from untrusted sources MUST validate that key parameters are consistent with the expected algorithm. An EC key MUST NOT be used in an RSA operation; a symmetric key MUST NOT be treated as an RSA public modulus. Failure to enforce this allows an attacker to construct a JWK that passes structural validation but enables signature forgery.
Algorithm confusion. If the alg member is not constrained, an attacker may substitute a weaker algorithm. Applications SHOULD fix the expected algorithm independently of the JWK or validate that the alg value is acceptable before use.
Key uniqueness. Applications maintaining a JWK Set SHOULD ensure kid values are unique within the set to prevent ambiguous key selection.
References
- RFC 7515 — Jones, M. et al., "JSON Web Signature (JWS)", May 2015.
- RFC 7516 — Jones, M., Hildebrand, J., "JSON Web Encryption (JWE)", May 2015.
- RFC 7518 — Jones, M., "JSON Web Algorithms (JWA)", May 2015.
- RFC 4648 — Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", October 2006.
atom.toml
# atom.toml — RFC 7517: JSON Web Key (JWK)
id = "schema-atoms/rfc/rfc-7517"
version = "1.0.0"
content_hash = "d61707e45c0cba606ae5298ee11cfa566fbee9781ce7f73ce292e350d4325346"
lifecycle = "draft"
created_at = "2026-05-24T00:00:00Z"
[rfc]
rfc_number = 7517
title = "JSON Web Key (JWK)"
authors = ["M. Jones"]
published_date = "2015-05"
status = "STANDARDS TRACK"
asset = "rfc7517.md"
asset_source = "rfc7517.txt"
[protocol]
provenance = "https://www.rfc-editor.org/rfc/rfc7517 — RFC 7517, May 2015, Jones. Part of the JOSE suite."
license = "IETF Trust"