https://github.com/altcha-org/altcha-lib-py
A lightweight Python library for creating and verifying ALTCHA challenges.
https://github.com/altcha-org/altcha-lib-py
altcha python
Last synced: about 9 hours ago
JSON representation
A lightweight Python library for creating and verifying ALTCHA challenges.
- Host: GitHub
- URL: https://github.com/altcha-org/altcha-lib-py
- Owner: altcha-org
- License: mit
- Created: 2024-07-26T13:14:19.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-06-07T11:43:29.000Z (6 days ago)
- Last Synced: 2025-06-12T20:32:01.784Z (about 9 hours ago)
- Topics: altcha, python
- Language: Python
- Homepage: https://altcha.org/
- Size: 45.9 KB
- Stars: 14
- Watchers: 2
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ALTCHA Python Library
The ALTCHA Python Library is a lightweight, zero-dependency library designed for creating and verifying [ALTCHA](https://altcha.org) challenges, specifically tailored for Python applications.
## Compatibility
This library is compatible with:
- Python 3.9+
## Example
- [Demo server](https://github.com/altcha-org/altcha-starter-py)
## Installation
To install the ALTCHA Python Library, use the following command:
```sh
pip install altcha
```
## Build
```sh
python -m build
```
## Tests
```sh
python -m unittest discover tests
```
## Usage
Here’s a basic example of how to use the ALTCHA Python Library:
```python
import datetime
from altcha import ChallengeOptions, create_challenge, verify_solution
def main():
hmac_key = "secret hmac key"
# Create a new challenge
options = ChallengeOptions(
expires=datetime.datetime.now() + datetime.timedelta(hours=1),
max_number=100000, # The maximum random number
hmac_key=hmac_key,
)
challenge = create_challenge(options)
print("Challenge created:", challenge)
# Example payload to verify
payload = {
"algorithm": challenge.algorithm,
"challenge": challenge.challenge,
"number": 12345, # Example number
"salt": challenge.salt,
"signature": challenge.signature,
}
# Verify the solution
ok, err = verify_solution(payload, hmac_key, check_expires=True)
if err:
print("Error:", err)
elif ok:
print("Solution verified!")
else:
print("Invalid solution.")
if __name__ == "__main__":
main()
```
## API
### `create_challenge(options)`
Creates a new challenge for ALTCHA.
**Parameters:**
- `options (dict)`:
- `algorithm (str)`: Hashing algorithm to use (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`, default: `'SHA-256'`).
- `max_number (int)`: Maximum number for the random number generator (default: 1,000,000).
- `salt_length (int)`: Length of the random salt in bytes (default: 12).
- `hmac_key (str)`: Required HMAC key.
- `salt (str)`: Optional salt string. If not provided, a random salt will be generated.
- `number (int)`: Optional specific number to use. If not provided, a random number will be generated.
- `expires (datetime)`: Optional expiration time for the challenge.
- `params (dict)`: Optional URL-encoded query parameters.
**Returns:** `Challenge`
### `verify_solution(payload, hmac_key, check_expires)`
Verifies an ALTCHA solution.
**Parameters:**
- `payload (dict)`: The solution payload to verify.
- `hmac_key (str)`: The HMAC key used for verification.
- `check_expires (bool)`: Indicates whether to validate the challenge's expiration. If set to True, the function checks the expires field within the salt (if present) to ensure the challenge has not expired.
(Note: To use this feature, the expires parameter must be included when creating the challenge.)
**Returns:** `(bool, str or None)`
### `extract_params(payload)`
Extracts URL parameters from the payload's salt.
**Parameters:**
- `payload (dict)`: The payload containing the salt.
**Returns:** `dict`
### `verify_fields_hash(form_data, fields, fields_hash, algorithm)`
Verifies the hash of form fields.
**Parameters:**
- `form_data (dict)`: The form data to hash.
- `fields (list)`: The fields to include in the hash.
- `fields_hash (str)`: The expected hash value.
- `algorithm (str)`: Hashing algorithm (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`).
**Returns:** `bool`
### `verify_server_signature(payload, hmac_key)`
Verifies the server signature.
**Parameters:**
- `payload (dict or str)`: The payload to verify (base64 encoded JSON string or dictionary).
- `hmac_key (str)`: The HMAC key used for verification.
**Returns:** `(bool, ServerSignatureVerificationData, str or None)`
### `solve_challenge(challenge, salt, algorithm, max_number, start, stop_chan)`
Finds a solution to the given challenge.
**Parameters:**
- `challenge (str)`: The challenge hash.
- `salt (str)`: The challenge salt.
- `algorithm (str)`: Hashing algorithm (`'SHA-1'`, `'SHA-256'`, `'SHA-512'`).
- `max_number (int)`: Maximum number to iterate to.
- `start (int)`: Starting number.
**Returns:** `Solution or None`
## License
MIT