or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

errors.mdindex.mdinterfaces.mdjwa.mdjwk.mdjws.mdutilities.md
tile.json

tessl/pypi-josepy

JOSE protocol implementation in Python with support for JSON Web Algorithms, Keys, and Signatures

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/josepy@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-josepy@2.1.0

index.mddocs/

JOSEPY

A comprehensive Python implementation of the JOSE (Javascript Object Signing and Encryption) standards developed by the IETF. Provides JSON Web Algorithms (JWA), JSON Web Key (JWK), and JSON Web Signature (JWS) functionality for secure token handling, digital signatures, and cryptographic key operations.

Package Information

  • Package Name: josepy
  • Language: Python
  • Installation: pip install josepy
  • License: Apache License 2.0
  • Homepage: https://github.com/certbot/josepy

Core Imports

import josepy

Common usage imports:

from josepy import JWK, JWS, Header, b64encode, b64decode
from josepy import RS256, ES256, HS256  # Signature algorithms
from josepy import JWKRSA, JWKEC, JWKOct  # Key types

Basic Usage

from josepy import JWKRSA, JWS, Header, RS256
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.backends import default_backend

# Generate RSA key pair
private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
    backend=default_backend()
)

# Create JWK from cryptography key
jwk = JWKRSA(key=private_key)

# Create JWS with payload
payload = b'{"msg": "Hello, JOSE!"}'
header = Header(alg=RS256)

# Sign the payload
jws = JWS.sign(payload, key=jwk, alg=RS256)

# Serialize to JSON
jws_json = jws.json_dumps()

# Verify signature (using public key)
public_jwk = jwk.public_key()
verified_jws = JWS.json_loads(jws_json)
is_valid = verified_jws.verify(public_jwk)
if is_valid:
    print(verified_jws.payload.decode())  # {"msg": "Hello, JOSE!"}
else:
    print("Signature verification failed")

Architecture

JOSEPY follows the JOSE standard architecture with three main components:

  • JSON Web Algorithms (JWA): Cryptographic algorithms for signing and verification
  • JSON Web Keys (JWK): Key representation and management for RSA, ECDSA, and symmetric keys
  • JSON Web Signature (JWS): Complete signing and verification workflow with headers and payloads

The library provides a type-safe, serializable interface built on the cryptography library for all cryptographic operations, with comprehensive error handling and RFC-compliant implementations.

Capabilities

JSON Web Algorithms (JWA)

Cryptographic signature algorithms supporting HMAC, RSA, and ECDSA variants with different hash functions. All algorithms provide sign() and verify() methods for secure token operations.

# Signature algorithm instances
RS256: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-256
RS384: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-384
RS512: JWASignature  # RSASSA-PKCS1-v1_5 using SHA-512
PS256: JWASignature  # RSASSA-PSS using SHA-256 and MGF1
PS384: JWASignature  # RSASSA-PSS using SHA-384 and MGF1
PS512: JWASignature  # RSASSA-PSS using SHA-512 and MGF1
ES256: JWASignature  # ECDSA using P-256 and SHA-256
ES384: JWASignature  # ECDSA using P-384 and SHA-384
ES512: JWASignature  # ECDSA using P-521 and SHA-512
HS256: JWASignature  # HMAC using SHA-256
HS384: JWASignature  # HMAC using SHA-384
HS512: JWASignature  # HMAC using SHA-512

JSON Web Algorithms

JSON Web Keys (JWK)

Key representation and management for RSA, Elliptic Curve, and symmetric keys with support for key loading, thumbprint generation, and public key extraction.

class JWK:
    def thumbprint(self, hash_function=hashes.SHA256) -> bytes: ...
    def public_key(self) -> 'JWK': ...
    @classmethod
    def from_json(cls, jobj) -> 'JWK': ...

class JWKRSA(JWK):
    def __init__(self, key=None): ...

class JWKEC(JWK):
    def __init__(self, key=None): ...

class JWKOct(JWK):
    def __init__(self, key=None): ...

JSON Web Keys

JSON Web Signature (JWS)

Complete signing and verification workflow with header and payload management, supporting multiple serialization formats and comprehensive validation.

class JWS:
    @classmethod
    def sign(cls, payload: bytes, **kwargs) -> 'JWS': ...
    def verify(self, key: Optional[JWK] = None) -> bool: ...
    def json_dumps(self, **kwargs) -> str: ...
    @classmethod
    def json_loads(cls, json_string: str) -> 'JWS': ...

class Header:
    def __init__(self, alg=None, **kwargs): ...

JSON Web Signature

Base64 and JSON Utilities

JOSE-compliant base64 encoding/decoding and JSON serialization utilities with support for certificates, CSRs, and typed field handling.

def b64encode(data: bytes) -> bytes: ...
def b64decode(data: Union[bytes, str]) -> bytes: ...
def encode_cert(cert: x509.Certificate) -> str: ...
def decode_cert(b64der: str) -> x509.Certificate: ...
def encode_csr(csr: x509.CertificateSigningRequest) -> str: ...
def decode_csr(b64der: str) -> x509.CertificateSigningRequest: ...

Base64 and JSON Utilities

Error Handling

Comprehensive error hierarchy for serialization, deserialization, and cryptographic operation failures with detailed error information.

class Error(Exception): ...
class DeserializationError(Error): ...
class SerializationError(Error): ...
class UnrecognizedTypeError(DeserializationError):
    def __init__(self, typ: str, jobj: Any): ...

Error Handling

JSON Serialization Interfaces

Core interfaces and base classes for JSON serialization and deserialization with support for partial and full serialization modes, implemented by all JOSE objects.

class JSONDeSerializable:
    def to_partial_json(self) -> Any: ...
    def to_json(self) -> Any: ...
    @classmethod
    def from_json(cls, jobj: Any) -> 'JSONDeSerializable': ...
    @classmethod
    def json_loads(cls, json_string: Union[str, bytes]) -> 'JSONDeSerializable': ...
    def json_dumps(self, **kwargs) -> str: ...
    def json_dumps_pretty(self) -> str: ...

JSON Serialization Interfaces

Types

class JSONDeSerializable:
    def to_partial_json(self) -> Any: ...
    def to_json(self) -> Any: ...
    @classmethod
    def from_json(cls, jobj: Any): ...
    def json_dumps(self, **kwargs) -> str: ...
    @classmethod
    def json_loads(cls, json_string: Union[str, bytes]): ...

class JSONObjectWithFields(JSONDeSerializable):
    """Base class for JSON objects with field definitions"""

class Field:
    """Field descriptor for JSON object properties"""

class ComparableKey:
    """Comparable wrapper for cryptography keys"""

class ImmutableMap:
    """Immutable key-to-value mapping with attribute access"""

class MediaType:
    """Media Type field encoder/decoder for JOSE headers"""
    PREFIX = "application/"
    @classmethod
    def decode(cls, value: str) -> str: ...
    @classmethod
    def encode(cls, value: str) -> str: ...