Encrypted Content Encoding for HTTP

1.2.1 · active · verified Sat Apr 11

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.

Warnings

gotcha 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.
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).
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.
gotcha 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.
Fix: Ensure the `version` string is consistently passed to both `encrypt` and `decrypt` functions. `aes128gcm` is the recommended and most modern version.
gotcha 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.
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.

Install

pip install http-ece Install latest version

Imports

encrypt
```
from http_ece import encrypt
```
decrypt
```
from http_ece import decrypt
```

Quickstart

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!")

view raw JSON →