{"id":3523,"library":"josepy","title":"JOSE Protocol Implementation in Python","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/certbot/josepy","tags":["jose","jws","jwe","jwt","cryptography","security"],"install":[{"cmd":"pip install josepy","lang":"bash","label":"Install josepy"}],"dependencies":[{"reason":"Provides core cryptographic primitives for JOSE operations.","package":"cryptography","optional":false}],"imports":[{"symbol":"JWSMessage","correct":"from josepy.jws import JWSMessage"},{"symbol":"RS256","correct":"from josepy.jwa import RS256"},{"symbol":"JWK","correct":"from josepy.jwk import JWK"},{"symbol":"Protected","correct":"from josepy.jws import Protected"}],"quickstart":{"code":"import os\nfrom josepy import jwa, jws\nfrom josepy.jwk import JWK\n\n# 1. Generate or load a private key for signing\n# In a production environment, load keys securely (e.g., from environment variables, KMS, or disk).\nkey_pem = os.environ.get('JOSEPY_PRIVATE_PRIVATE_KEY_PEM', None)\nif key_pem:\n    private_key = JWK.load(key_pem.encode('utf-8'))\nelse:\n    # Generate a new RSA key for demonstration purposes\n    private_key = jwa.RS256.create().key\n    print(\"Generated a new RSA private key for demonstration. In production, load securely.\")\n\n# 2. Define the payload and protected header\npayload = b\"Hello, josepy! This is a signed message.\"\nprotected_header = jws.Protected({\"alg\": \"RS256\", \"jwk\": private_key.public_key.json_serializable})\n\n# 3. Sign the message\nsigner = jwa.RS256.create(key=private_key)\njws_msg = jws.JWSMessage.sign(\n    payload=payload,\n    alg=jwa.RS256,\n    key=private_key,\n    protected=protected_header,\n)\n\nserialized_jws = jws_msg.json_dumps(indent=2).decode('utf-8')\nprint(f\"\\nSigned JWS:\\n{serialized_jws}\")\n\n# 4. Verify the message\n# The verifier typically has the public key corresponding to the signer's private key.\nparsed_jws = jws.JWSMessage.json_loads(serialized_jws.encode('utf-8'))\n\ntry:\n    verified_payload = parsed_jws.verify(\n        verifier_key=private_key.public_key, # Use the public key for verification\n        alg=jwa.RS256\n    )\n    print(f\"\\nVerification successful! Payload: {verified_payload.decode('utf-8')}\")\n    assert verified_payload == payload\nexcept Exception as e:\n    print(f\"\\nVerification failed: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python interpreter to 3.9.2 or newer.","message":"As of josepy 2.2.0, Python versions older than 3.9.2 are no longer supported. Ensure your environment meets this minimum requirement.","severity":"breaking","affected_versions":">=2.2.0"},{"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.","message":"josepy 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Choosing 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Secure 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}