Registry / http-networking / http-ece

http-ece

JSON →
library1.2.1pypypi✓ verified 22d ago

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.

pip install http-ece
INSTALL
IMPORT
SIG · HTTP-ECE
H
http-ece
http-networkingpythonv1.2.1
Install
3.2s avg
Import
74ms
Disk
34MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.1 · 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.078s · 36.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.2s · import 0.070s · 37MB
34MB installed
● package 34MB
Code
Verified usage

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

encrypt
from http_ece import encrypt
decrypt
from http_ece import decrypt

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.

import os from http_ece import encrypt, decrypt # --- Basic Content Encryption/Decryption --- # This example demonstrates content encryption without Diffie-Hellman key agreement. # In a real Web Push scenario, 'auth_secret' and 'salt' are often derived # or exchanged as part of the Web Push protocol. # Generate a random content encryption key (CEK) and salt # In a real application, securely manage and transport these values. cek = os.urandom(16) salt = os.urandom(16) auth_secret = os.urandom(16) # A secret known to both sender and receiver plaintext_data = b"This is a secret message to be encrypted." # Encrypt the plaintext encrypted_payload, record_size = encrypt( plaintext_data, private_key=None, # Not used for simple content encryption dh=None, # Not used for simple content encryption auth_secret=auth_secret, salt=salt, keyid=b'', key=cek, version='aes128gcm' # Recommended version ) print(f"Original plaintext: {plaintext_data.decode()}") print(f"Encrypted payload (hex): {encrypted_payload.hex()}") print(f"Record size used for encryption: {record_size}") # Decrypt the payload decrypted_data = decrypt( encrypted_payload, private_key=None, # Not used for simple content encryption dh=None, # Not used for simple content encryption auth_secret=auth_secret, salt=salt, keyid=b'', key=cek, rs=record_size, # Must be the same record size used for encryption version='aes128gcm' ) print(f"Decrypted plaintext: {decrypted_data.decode()}") assert plaintext_data == decrypted_data print("Encryption and decryption successful!")
Debug
Known issues
gotchaCryptographic 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.
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).
affects: All
gotcha`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.
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.
affects: All
gotchaThe `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.
fix
Ensure the `version` string is consistently passed to both `encrypt` and `decrypt` functions. `aes128gcm` is the recommended and most modern version.
affects: All
gotchaThe `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.
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.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'http_ece'
Developers attempt to import the library using the hyphenated package name `http-ece` as `http_ece`, which is the correct Python module name, but they might be encountering this if the package was not correctly installed, or if an environment path issue prevents Python from finding it. This can also happen if they incorrectly try `import http-ece`.
fix
Ensure the package is installed using `pip install http-ece`. The correct import statement is `import http_ece`.
TypeError: argument 'plaintext' must be bytes, not str
The `http-ece` library, being a cryptographic library, expects byte strings (e.g., `bytes`) for operations like encryption and decryption, not regular Python Unicode strings (`str`).
fix
Convert string data to bytes using `.encode('utf-8')` before passing it to `http_ece` functions, and decode byte results to strings using `.decode('utf-8')` if necessary. Example: `encrypted_data = http_ece.encrypt(plaintext.encode('utf-8'), ...)`
ValueError: Decryption failed (or similar for invalid padding/truncated content)
This error occurs during decryption when the provided encrypted content, salt, or keying material is corrupted, incorrect, or does not conform to the Encrypted Content Encoding (ECE) specification (e.g., incorrect padding, truncated data).
fix
Verify that the encrypted content, salt, and keys (including DH key, authentication secret) used for decryption are exactly the same and correctly derived from what was used during encryption, and that the encrypted payload has not been modified or truncated in transit.
Upgrade
Version history
1.2.1latest on PyPI · released Aug 8, 2024
Audit
Dependencies
cryptographyrequiredProvides the underlying cryptographic primitives (AES-GCM, HKDF, EC) required for Encrypted Content Encoding.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources