DOCSEARCHbyAlgolia
Submit Docs

joserfc

repository·main·Indexed 41 days ago

https://github.com/authlib/joserfc

A comprehensive Python library for implementing JSON Object Signing and Encryption (JOSE) standards. It provides full support for JWS (RFC 7515), JWE (RFC 7516), JWK (RFC 7517), JWA (RFC 7518), and JWT (RFC 7519), along with various other RFCs and draft implementations such as C20P, XC20P, and ECDH-1PU.

Tokens
37.2K
Snippets
122
Records
160
Agent score
50%

What's inside joserfc

  1. Overview of JWS, JWE, JWK, and JWT interfaces

    main

    The joserfc library provides interfaces for the core components of the JOSE (JSON Object Signing and Encryption) framework:

    • JWS (JSON Web Signature): Used for encoding and signing data. Most JSON Web Tokens (JWTs) use JWS in compact serialization.
    • JWE (JSON Web Encryption): Used for representing encrypted content using JSON-based data structures.
    • JWK (JSON Web Key): Provides key management through specific key types like OctKey, RSAKey, ECKey, OKPKey, and JSON Web Key Sets (JWK Sets).
    • JWT (JSON Web Token): A high-level token format built on top of either JWS or JWE.

  2. Introduction to joserfc

    main

    joserfc is a specialized Python library providing a comprehensive implementation of JSON Object Signing and Encryption (JOSE) standards. It is a standalone, redesigned version of the JOSE modules from Authlib, specifically optimized for modularity and ease of use.

    Use joserfc when you need to work with the following standards in your Python applications:

    • JWS (JSON Web Signature)
    • JWE (JSON Web Encryption)
    • JWK (JSON Web Key)
    • JWA (JSON Web Algorithms)
    • JWT (JSON Web Token)

  3. Overview of joserfc standards and RFC support

    main

    joserfc is a Python library providing implementations for several JSON Object Signing and Encryption (JOSE) standards. It features a redesigned API specifically for JOSE functionality and supports the following RFCs:

    • RFC 7515: JSON Web Signature (JWS)
    • RFC 7516: JSON Web Encryption (JWE)
    • RFC 7517: JSON Web Key (JWK)
    • RFC 7518: JSON Web Algorithms (JWA)
    • RFC 7519: JSON Web Token (JWT)
    • RFC 7520: Examples of Protecting Content Using JOSE
    • RFC 7638: JWK thumbprint
    • RFC 7797: JWS Unencoded Payload Option
    • RFC 8037: OKPKey and EdDSA algorithm
    • RFC 8812: ES256K algorithm and ECKey with curve secp256k1
    • RFC 9278: JWK Thumbprint URI (thumbprint_uri)
    • RFC 9864: Ed25519 and Ed448 algorithms

    It also includes draft implementations for chacha20 and ecdh1pu.

  4. Supported JOSE RFC standards in joserfc

    main

    joserfc provides implementations for the following standards:

    • RFC7515: JSON Web Signature (JWS)
    • RFC7516: JSON Web Encryption (JWE)
    • RFC7517: JSON Web Key (JWK)
    • RFC7518: JSON Web Algorithms (JWA)
    • RFC7519: JSON Web Token (JWT)
    • RFC7520: Examples of Protecting Content Using JOSE
    • RFC7638: JSON Web Key (JWK) Thumbprint
    • RFC7797: JWS Unencoded Payload Option
    • RFC8037: OKP Key and EdDSA algorithm
    • RFC8812: ES256K algorithm
    • RFC9278: JWK Thumbprint URI
    • RFC9864: Ed25519 and Ed448 algorithms

    It also includes draft implementations for:

    • C20P and XC20P algorithms
    • Key Agreement with Elliptic Curve Diffie-Hellman One-Pass Unified Model (ECDH-1PU)
    • draft-ietf-jose-deprecate-none-rsa15-02

  5. Compare joserfc with other Python JOSE libraries

    main

    If you are deciding between libraries, joserfc is positioned as a highly feature-complete implementation of the JOSE specifications. Key advantages over other libraries like pyjwt, python-jose, or jwcrypto include:

    • Full Type Hint Support: Unlike authlib.jose, python-jose, or jwcrypto.
    • Comprehensive JWE Support: Supports both Compact and JSON JWE formats (which pyjwt lacks).
    • Advanced RFC Coverage: Provides support for RFC7797, RFC9278, and RFC9864, which are missing or limited in other libraries.
    • Key Management: Provides full support for key generation and importing, which is a limitation in pyjwt and python-jose.

  6. What is a JSON Web Key (JWK) and a JWK Set (JWKS)?

    main

    RFC 7517 defines the JSON Web Key (JWK) specification, which is a standard format for representing cryptographic keys (public, private, or symmetric) as JSON objects. This allows for interoperable key representation across JWS, JWE, and other JOSE operations.

    JWK Object

    A single JSON object representing one key. Key parameters include:

    • kty: The key type (required), e.g., RSA, EC, or oct.
    • use: Intended usage, such as sig (signature) or enc (encryption).
    • key_ops: A list of permitted operations (e.g., sign, verify, wrapKey).
    • kid: A unique key identifier.
    • alg: The intended algorithm.
    • x5u / x5c / x5t: Parameters for X.509 certificate chains.

    JWK Set (JWKS)

    A JSON object containing an array of JWKs, typically used for key rotation or multi-tenant environments. It follows this structure:

    {
  "keys": [
    { "kty": "RSA", ... },
    { "kty": "EC", ... }
  ]
}

  7. What is RFC 7515 (JSON Web Signature)?

    main
    RFC 7515 defines the JSON Web Signature (JWS) specification, which provides a framework for representing digitally signed or MAC-protected content using JSON-based data structures. It allows for the creation and validation of signatures to ensure data integrity and authenticity.

  8. What is RFC 7797 and the b64 header parameter?

    main

    RFC 7797 is an extension to RFC 7515 (JWS) that allows a JWS payload to be transmitted without Base64URL encoding. This is achieved using the b64 header parameter.

    The b64 Parameter Behavior

    • b64 = true (default): The payload is Base64URL-encoded before signing.
    • b64 = false: The payload is included as-is (binary or text) without encoding.

    Requirements for b64 = false

    When using an unencoded payload, the following constraints must be met to ensure interoperability:

    1. The b64 parameter must appear in the protected header.
    2. The crit (critical) header parameter must include "b64" so that recipients are aware of the unencoded payload behavior.
    3. The signing input is modified to reflect the unencoded state of the payload.

  9. What is RFC 7516 (JSON Web Encryption)

    main
    RFC 7516 defines JSON Web Encryption (JWE), a specification for representing encrypted content using JSON-based data structures. It provides a framework for encrypting arbitrary payloads, managing keys, and representing encryption parameters through two primary serialization formats: Compact and JSON serialization.

  10. JSON Serialization for JWE

    main

    JSON serialization expresses a JWE as a JSON object. Unlike compact serialization, it is used for more complex use cases, such as:

    • Encrypting for multiple recipients.
    • Including per-recipient header parameters.
    • Debugging or inspecting encryption metadata.

    A JSON-serialized JWE typically includes:

    • protected: A Base64URL-encoded header shared across recipients.
    • unprotected: An unprotected shared header (optional).
    • iv: The initialization vector.
    • ciphertext: The encrypted payload.
    • tag: The authentication tag.
    • recipients: An array of recipient objects, each containing:
      • header: Per-recipient unprotected header (optional).
      • encrypted_key: A CEK encrypted for that recipient.

  11. How the Registry works for JWS and JWE

    main

    The registry is a central component used to manage and enforce security constraints for JSON Web Signature (JWS) and JSON Web Encryption (JWE). It is responsible for:

    • Storing and validating supported and allowed algorithms.
    • Managing registered header parameters.
    • Providing methods to validate both algorithms and headers during serialization or encryption.

    While the documentation uses JWSRegistry as a reference, JWERegistry follows identical behavior and logic.

  12. Support for RFC 8812 (secp256k1) in joserfc

    main

    The joserfc library provides full support for RFC 8812, which defines the use of the secp256k1 elliptic curve for JSON Web Signatures (JWS) and JSON Web Keys (JWK). This is particularly useful for integration with blockchain ecosystems.

    Key identifiers introduced by this RFC and supported by joserfc:

    • JWS algorithm: ES256K
    • JWK elliptic curve: secp256k1