ALTCHA Python Library

The ALTCHA Python Library is a lightweight, zero-dependency library designed for creating and verifying ALTCHA challenges, specifically tailored for Python applications.

Compatibility

• Python 3.9+

Example

• examples/server.py

Installation

pip install altcha

For Argon2id support (optional):

pip install altcha argon2-cffi

Tests

python -m unittest discover tests

PoW v2

PoW v2 replaces the simple hash-matching approach of v1 with a key derivation function (KDF) proof of work. Instead of finding a number whose hash equals a target, the client must find a counter value whose derived key starts with a required prefix. This enables memory-hard algorithms (Argon2id, scrypt) that are more resistant to GPU/ASIC attacks.

Algorithms

Quick start

from altcha import (
    create_challenge,
    solve_challenge,
    verify_solution,
    Payload,
)

HMAC_SECRET = "secret hmac key"

# Server: create a challenge
challenge = create_challenge(
    algorithm="PBKDF2/SHA-256",
    cost=5_000,
    hmac_secret=HMAC_SECRET,
)

# Client: solve the challenge
solution = solve_challenge(challenge)
if solution is None:
    raise RuntimeError("Challenge could not be solved in time")

# Client: encode and transmit the payload
payload_b64 = Payload(challenge, solution).to_base64()

# Server: verify
result = verify_solution(payload_b64, HMAC_SECRET)
print(result.verified)  # True

Deterministic mode

Pass a counter to create_challenge to pre-solve the challenge. The derived key prefix is embedded in the challenge so the client must find exactly that counter. Combine with hmac_key_secret to enable fast server-side verification without re-deriving the key.

import secrets

counter = secrets.randbelow(5_000) + 5_000

challenge = create_challenge(
    algorithm="PBKDF2/SHA-256",
    cost=5_000,
    counter=counter,
    hmac_secret=HMAC_SECRET,
    hmac_key_secret="key-signing-secret",
)

solution = solve_challenge(challenge)
if solution is None:
    raise RuntimeError("Challenge could not be solved in time")
payload_b64 = Payload(challenge, solution).to_base64()

result = verify_solution(
    payload_b64,
    HMAC_SECRET,
    hmac_key_secret="key-signing-secret",  # enables fast path
)
print(result.verified)  # True

Expiry

import datetime

challenge = create_challenge(
    algorithm="PBKDF2/SHA-256",
    cost=5_000,
    expires_at=datetime.datetime.now(datetime.timezone.utc)
    + datetime.timedelta(minutes=10),
    hmac_secret=HMAC_SECRET,
)

Custom derive_key

Pass your own derive_key function to use a custom or third-party KDF:

def my_derive_key(parameters, salt: bytes, password: bytes) -> bytes: ...


challenge = create_challenge(
    algorithm="MY-ALGO",
    cost=1,
    derive_key=my_derive_key,
    hmac_secret=HMAC_SECRET,
)

PoW v1 (legacy)

The original ALTCHA proof of work. The client brute-forces a number n such that hash(salt + n) == challenge. Available under the _v1 / V1 suffix.

API reference

V2

create_challenge(algorithm, cost, *, derive_key, counter, key_length, key_prefix, key_prefix_length, memory_cost, parallelism, expires_at, data, hmac_secret, hmac_key_secret, hmac_algorithm) → Challenge

Create a new v2 proof-of-work challenge.

Returns Challenge.

solve_challenge(challenge, derive_key, *, counter_start, counter_step, timeout) → Solution | None

Solve a v2 challenge by brute-forcing counter values.

Returns Solution or None.

verify_solution(payload, hmac_secret, derive_key, *, hmac_key_secret, hmac_algorithm) → VerifySolutionResult

Verify a v2 challenge solution.

Returns VerifySolutionResult with fields:

Built-in derive_key functions

Server Signature Verification

verify_fields_hash(form_data, fields, fields_hash, algorithm) → bool

Verifies the hash of specific form fields.

verify_server_signature(payload, hmac_key) → (bool, ServerSignatureVerificationData | None, str | None)

Verifies an ALTCHA server signature.

verify_server(payload, url, secret, *, headers, timeout, retries, retry_delay, retry_backoff, http_post) → VerifyServerResult

Verifies a payload remotely via the ALTCHA Sentinel /v1/verify/signature API, instead of checking the HMAC signature locally. Avoids managing the HMAC secret on your server, at the cost of a network round-trip.

from altcha import verify_server

result = verify_server(
    payload,  # the payload received from POST /v1/verify
    url="https://sentinel.example.com/v1/verify/signature",
    secret=API_KEY_SECRET,  # optional, checked against the payload's API key
    timeout=10,
    retries=2,
)

if result.verified:
    ...

Returns VerifyServerResult with fields:

V1 (legacy)

create_challenge_v1(options) → ChallengeV1

Creates a new v1 challenge.

ChallengeOptionsV1 parameters:

verify_solution_v1(payload, hmac_secret, check_expires) → (bool, str | None)

Verifies a v1 solution payload.

solve_challenge_v1(challenge, salt, algorithm, max_number, start) → SolutionV1 | None

Brute-forces a v1 challenge.

extract_params_v1(payload) → dict

Extracts URL parameters from the payload's salt.

License

MIT