RFC 7517

RFC7517 defines the JSON Web Key (JWK) specification, a standard format for representing cryptographic keys using JSON. It provides a flexible and interoperable way to describe public keys, private keys, and symmetric keys for use with JWS, JWE, and other JOSE-related operations.

Definition

RFC 7517 specifies how cryptographic keys are expressed as JSON objects and how sets of keys are represented. The specification defines:

JWK Object

A JWK is a JSON object representing a single cryptographic key. Each JWK contains a set of required and optional parameters depending on the key type. Common parameters include:

  • kty — the key type (required), such as RSA, EC, or oct

  • use — intended key usage (sig for signature, enc for encryption)

  • key_ops — a list of permitted operations (sign, verify, wrapKey, etc.)

  • kid — a key identifier for selecting a specific key

  • alg — the algorithm for which the key is intended

  • x5u / x5c / x5t — X.509 certificate chain parameters

JWK Set (JWKS)

A JWK Set is a JSON object that contains an array of JWKs. It is commonly used for publishing multiple keys, such as rotation sets or multi-tenant public keys:

{
  "keys": [
    { ... JWK 1 ... },
    { ... JWK 2 ... }
  ]
}

JWKS documents are frequently served over HTTPS endpoints, allowing clients to discover signing keys dynamically (e.g., OAuth 2.0, OpenID Connect).

Key Usage and Operations

A JWK may declare either:

  • use — a coarse-grained indication of intended purpose (e.g., sig or enc), or

  • key_ops — a precise list of permissible operations (e.g., sign, verify, encrypt, unwrapKey)

These fields help recipients determine how a key should be used and prevent unintended or insecure key usage.

Implementation

All definitions from RFC 7517 are fully implemented in joserfc.

Private modules

The underlying logic resides in the private module joserfc/_rfc7517, which defines:

  • Base key models

  • Utilities for handling PEM keys

Public exports

Public classes and utilities are re-exported through joserfc.jwk. You should always use joserfc.jwk for working with JWK objects and JWK Sets, rather than importing from the private module directly.

This includes functionality for:

  • parsing JWK and JWKs: jwk.import_key

  • constructing JWK and JWKs: jwk.generate_key