.. _rfc7517:

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:

.. code-block:: text

    {
      "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``