Altcha V2 module provides functions for creating and verifying ALTCHA v2 challenges.
V2 uses key derivation functions (PBKDF2, iterative SHA) instead of simple hashing,
allowing for tunable computational difficulty. The proof-of-work mechanism finds a
counter value such that deriveKey(nonce ++ counter, salt) starts with a required
hex prefix.
Supported algorithms
"SHA-256","SHA-384","SHA-512"— iterative SHA hashing (built-in)"PBKDF2/SHA-256","PBKDF2/SHA-384","PBKDF2/SHA-512"— PBKDF2 (built-in, OTP 24+)- Custom algorithms — pass a
derive_key_fnoption
Basic usage
options = %Altcha.V2.CreateChallengeOptions{
algorithm: "PBKDF2/SHA-256",
cost: 10_000,
hmac_signature_secret: "my_secret"
}
challenge = Altcha.V2.create_challenge(options)
# Verify a client-submitted payload
payload = Altcha.V2.decode_payload(client_b64_string)
result = Altcha.V2.verify_solution(%Altcha.V2.VerifySolutionOptions{
challenge: payload.challenge,
solution: payload.solution,
hmac_signature_secret: "my_secret"
})Summary
Functions
Creates a new V2 PoW challenge.
Decodes a Base64-encoded JSON payload from a client into a %Altcha.V2.Payload{}.
Solves a V2 challenge by brute-forcing counter values until the derived key starts with the required prefix.
Verifies if the hash of form fields matches the provided hash.
Verifies a server signature payload issued by the Altcha verification service.
Verifies a client-submitted V2 solution against the original challenge.
Functions
Creates a new V2 PoW challenge.
Generates a random nonce and salt, computes the challenge parameters,
and optionally signs them with HMAC using hmac_signature_secret.
Options
See Altcha.V2.CreateChallengeOptions for all available options.
Examples
challenge = Altcha.V2.create_challenge(%Altcha.V2.CreateChallengeOptions{
algorithm: "PBKDF2/SHA-256",
cost: 10_000,
hmac_signature_secret: "my_secret"
})Decodes a Base64-encoded JSON payload from a client into a %Altcha.V2.Payload{}.
Solves a V2 challenge by brute-forcing counter values until the derived key starts with the required prefix.
Returns a %Altcha.V2.Solution{} on success, or nil if timed out.
Options
See Altcha.V2.SolveChallengeOptions for all available options.
Verifies if the hash of form fields matches the provided hash.
Verifies a server signature payload issued by the Altcha verification service.
Accepts a %Altcha.V2.ServerSignaturePayload{} struct, a plain map with string
keys, a raw JSON string, or a Base64-encoded JSON string.
Returns {%VerifySolutionResult{}, verification_data | nil} where
verification_data is a map of typed values parsed from the URL-encoded
verificationData query string.
The VerifySolutionResult fields:
expired—expiretimestamp in the verification data has passedinvalid_signature— HMAC ofhash(verificationData)does not matchinvalid_solution—verifiedis nottruein the data or payload
Verifies a client-submitted V2 solution against the original challenge.
Performs the following checks in order:
- Whether the challenge has expired
- Whether the challenge has a signature
- Whether the challenge signature is valid (tamper protection)
- Whether the solution is valid (via key signature or re-derivation)
Returns a %Altcha.V2.VerifySolutionResult{}.
Options
See Altcha.V2.VerifySolutionOptions for all available options.