{"id":4041,"library":"http-ece","title":"Encrypted Content Encoding for HTTP","description":"http-ece is a Python library that implements Encrypted Content Encoding for HTTP, primarily used in contexts like Web Push to secure payload data. It provides functions to encrypt and decrypt arbitrary byte strings using AES-GCM with a derived keying material. The current version is 1.2.1, and the library has an infrequent release cadence, with the most recent update in August 2024, indicating active maintenance.","status":"active","version":"1.2.1","language":"en","source_language":"en","source_url":"https://github.com/web-push-libs/encrypted-content-encoding","tags":["encryption","http","web push","security","cryptography"],"install":[{"cmd":"pip install http-ece","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the underlying cryptographic primitives (AES-GCM, HKDF, EC) required for Encrypted Content Encoding.","package":"cryptography","optional":false}],"imports":[{"symbol":"encrypt","correct":"from http_ece import encrypt"},{"symbol":"decrypt","correct":"from http_ece import decrypt"}],"quickstart":{"code":"import os\nfrom http_ece import encrypt, decrypt\n\n# --- Basic Content Encryption/Decryption ---\n# This example demonstrates content encryption without Diffie-Hellman key agreement.\n# In a real Web Push scenario, 'auth_secret' and 'salt' are often derived\n# or exchanged as part of the Web Push protocol.\n\n# Generate a random content encryption key (CEK) and salt\n# In a real application, securely manage and transport these values.\ncek = os.urandom(16)\nsalt = os.urandom(16)\nauth_secret = os.urandom(16) # A secret known to both sender and receiver\n\nplaintext_data = b\"This is a secret message to be encrypted.\"\n\n# Encrypt the plaintext\nencrypted_payload, record_size = encrypt(\n    plaintext_data,\n    private_key=None, # Not used for simple content encryption\n    dh=None,          # Not used for simple content encryption\n    auth_secret=auth_secret,\n    salt=salt,\n    keyid=b'',\n    key=cek,\n    version='aes128gcm' # Recommended version\n)\n\nprint(f\"Original plaintext: {plaintext_data.decode()}\")\nprint(f\"Encrypted payload (hex): {encrypted_payload.hex()}\")\nprint(f\"Record size used for encryption: {record_size}\")\n\n# Decrypt the payload\ndecrypted_data = decrypt(\n    encrypted_payload,\n    private_key=None, # Not used for simple content encryption\n    dh=None,          # Not used for simple content encryption\n    auth_secret=auth_secret,\n    salt=salt,\n    keyid=b'',\n    key=cek,\n    rs=record_size,   # Must be the same record size used for encryption\n    version='aes128gcm'\n)\n\nprint(f\"Decrypted plaintext: {decrypted_data.decode()}\")\n\nassert plaintext_data == decrypted_data\nprint(\"Encryption and decryption successful!\")","lang":"python","description":"This quickstart demonstrates how to encrypt and decrypt a simple byte string using `http-ece` for content encoding. It uses randomly generated keys and salts, which must be securely managed and shared in a production environment. The example focuses on `aes128gcm` version for content encryption without Diffie-Hellman key agreement."},"warnings":[{"fix":"Implement robust key management practices suitable for your application's security requirements (e.g., key derivation, secure storage, authenticated key exchange like Web Push's Diffie-Hellman).","message":"Cryptographic secrets (keys, salts, auth_secret) must be handled securely. Generating them with `os.urandom()` is suitable for examples, but in production, these must be securely generated, stored, and exchanged, as their compromise directly breaks security.","severity":"gotcha","affected_versions":"All"},{"fix":"Always convert string inputs to bytes using `.encode('utf-8')` before passing them to `encrypt` or `decrypt` functions. Ensure keys and salts are also byte objects.","message":"`http-ece` functions expect `bytes` for all cryptographic inputs (plaintext, keys, salts). Passing regular Python strings (`str`) will result in `TypeError` or incorrect encryption/decryption, as explicit encoding to bytes is required.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure the `version` string is consistently passed to both `encrypt` and `decrypt` functions. `aes128gcm` is the recommended and most modern version.","message":"The `version` parameter passed to `encrypt` and `decrypt` must be identical (e.g., `'aes128gcm'`). Mismatching versions will lead to `ECEException` during decryption, as the cryptographic parameters will be incompatible.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your build/deployment environment has the necessary development tools (`gcc`, `python-dev`, etc.) to compile `cryptography`. Refer to `cryptography`'s official documentation for detailed prerequisites.","message":"The `http-ece` library depends on `cryptography`, which often requires C compiler toolchains during installation, especially on systems without pre-built wheels. This can be a point of failure in deployment environments.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}