Registry / auth-security / josepy

josepy

JSON →
library2.2.0pypypi✓ verified 23d ago

josepy is a Python library that implements the JOSE (JSON Object Signing and Encryption) protocol, providing cryptographic primitives for creating and verifying JWS (JSON Web Signatures) and JWE (JSON Web Encryption) messages. It serves as a foundational cryptography component for projects like Certbot. The current version is 2.2.0, with releases typically aligned with Certbot updates or critical security fixes for its dependencies.

pip install josepy
INSTALL
IMPORT
SIG · JOSEPY
J
josepy
auth-securitypythonv2.2.0
Install
2.4s avg
Import
355ms
Disk
33MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.356s · 35.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.4s · import 0.354s · 36MB
33MB installed
● package 33MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

JSONDeSerializable
from josepy import JSONDeSerializable
from josepy.jws import JWSMessage
JWK
from josepy import JWK
JWS
from josepy import JWS

This quickstart demonstrates how to generate an RSA key (or load an existing one), sign a JWS message with it, serialize the JWS, and then verify it using the corresponding public key. Remember to handle private keys securely in production environments.

import os from josepy import jwa, jws from josepy.jwk import JWK # 1. Generate or load a private key for signing # In a production environment, load keys securely (e.g., from environment variables, KMS, or disk). key_pem = os.environ.get('JOSEPY_PRIVATE_PRIVATE_KEY_PEM', None) if key_pem: private_key = JWK.load(key_pem.encode('utf-8')) else: # Generate a new RSA key for demonstration purposes private_key = jwa.RS256.create().key print("Generated a new RSA private key for demonstration. In production, load securely.") # 2. Define the payload and protected header payload = b"Hello, josepy! This is a signed message." protected_header = jws.Protected({"alg": "RS256", "jwk": private_key.public_key.json_serializable}) # 3. Sign the message signer = jwa.RS256.create(key=private_key) jws_msg = jws.JWSMessage.sign( payload=payload, alg=jwa.RS256, key=private_key, protected=protected_header, ) serialized_jws = jws_msg.json_dumps(indent=2).decode('utf-8') print(f"\nSigned JWS:\n{serialized_jws}") # 4. Verify the message # The verifier typically has the public key corresponding to the signer's private key. parsed_jws = jws.JWSMessage.json_loads(serialized_jws.encode('utf-8')) try: verified_payload = parsed_jws.verify( verifier_key=private_key.public_key, # Use the public key for verification alg=jwa.RS256 ) print(f"\nVerification successful! Payload: {verified_payload.decode('utf-8')}") assert verified_payload == payload except Exception as e: print(f"\nVerification failed: {e}")
Debug
Known issues
breakingAs of josepy 2.2.0, Python versions older than 3.9.2 are no longer supported. Ensure your environment meets this minimum requirement.
fix
Upgrade your Python interpreter to 3.9.2 or newer.
affects: >=2.2.0
gotchajosepy relies on the `cryptography` library for its core cryptographic operations. Updates to `cryptography` can sometimes introduce breaking changes or require specific versions. While josepy abstracts much of this, ensure `cryptography` and `josepy` versions are compatible, especially when dealing with new features or security patches.
fix
Carefully manage `cryptography` dependency versions in your project's `requirements.txt` or `pyproject.toml` to ensure stability. Refer to josepy's `setup.py` for its exact dependency requirements.
affects: All versions
gotchaChoosing weak or deprecated algorithms (e.g., 'none' for `alg`) can lead to severe security vulnerabilities. josepy provides the flexibility to use various algorithms, but it is the user's responsibility to select cryptographically strong and appropriate ones for their use case.
fix
Always use strong, recommended cryptographic algorithms (e.g., RS256, PS256, ES256) and avoid insecure options. Keep up-to-date with current cryptographic best practices.
affects: All versions
gotchaSecure management of private keys is paramount. josepy provides the cryptographic primitives, but it does not dictate how keys should be stored or accessed. Storing private keys insecurely (e.g., directly in code, unencrypted on disk) can lead to full system compromise.
fix
Implement robust key management practices: use environment variables, hardware security modules (HSMs), key management services (KMS), or encrypted storage for private keys. Never hardcode private keys.
affects: All versions
Upgrade
Version history
2.2.0latest on PyPI · released Oct 14, 2025
Audit
Dependencies
cryptographyrequiredProvides core cryptographic primitives for JOSE operations.
Agent activity
24 hits · last 30 days
node
22
OpenAI (training)
1
Resources