ALTCHA Elixir Library

The ALTCHA Elixir Library is a lightweight library designed for creating and verifying ALTCHA challenges.

Compatibility

This library is compatible with:

• Elixir 1.10+

Example

• Demo server

Installation

To install the ALTCHA Elixir Library, add it to your mix.exs dependencies:

defp deps do
  [
    {:altcha, "~> 0.2"}
  ]
end

Then run:

mix deps.get

Usage

Here’s a basic example of how to use the ALTCHA Elixir Library:

hmac_key = "secret hmac key"

# Create a new challenge
options = %Altcha.ChallengeOptions{
  hmac_key: hmac_key,
  max_number: 100000 # the maximum random number
}

challenge = Altcha.create_challenge(options)

# Example payload to verify
payload = %{
  algorithm: challenge.algorithm,
  challenge: challenge.challenge,
  number: 123, # Example number
  salt: challenge.salt,
  signature: challenge.signature
}

# Verify the solution
valid = Altcha.verify_solution(payload, hmac_key, true)

API Documentation

create_challenge/1

Description:

Generates a new ALTCHA challenge with the specified options. The challenge includes a hashed string and an HMAC signature.

Parameters:

• %ChallengeOptions{} - A struct containing options for challenge creation:

  • :algorithm - (optional) The algorithm to use for hashing (:sha, :sha256, :sha512). Defaults to :sha256.
  • :max_number - (optional) The maximum number for challenge generation. Defaults to 1_000_000.
  • :salt_length - (optional) The length of the salt. Defaults to 12.
  • :hmac_key - (required) Key used for HMAC calculation.
  • :salt - (optional) The salt value. If not provided, a random salt will be generated.
  • :number - (optional) The number for the challenge. If not provided, a random number will be generated.
  • :expires - (optional) Expiration time for the challenge in seconds from the current time.
  • :params - (optional) Additional parameters to include in the salt.

Returns:

A %Challenge{} struct containing:

• :algorithm - The hashing algorithm used.
• :challenge - The hashed challenge string.
• :maxnumber - The maximum number used.
• :salt - The salt used.
• :signature - The HMAC signature of the challenge.

---

verify_solution/2

Description:

Verifies a given solution by checking its validity and comparing it with the expected challenge.

Parameters:

• payload - The payload containing challenge details. Can be a %Payload{} struct, a JSON object, or a Base64-encoded string.
• hmac_key - The key used for HMAC calculation.

Options:

• check_expires - (optional) A boolean to determine if the expiration of the challenge should be checked. Defaults to true.

Returns:

true if the solution is valid and matches the expected challenge; otherwise, false.

---

verify_fields_hash/4

Description:

Verifies if the hash of form fields matches the provided hash.

Parameters:

• form_data - The form data as a map with field names and values.
• fields - A list of field names to be included in the hash calculation.
• fields_hash - The expected hash of the form fields.
• algorithm - The algorithm used for hashing (:sha, :sha256, :sha512).

Returns:

true if the computed hash of the fields matches the provided hash; otherwise, false.

---

verify_server_signature/2

Description:

Verifies the server signature using the provided payload and HMAC key.

Parameters:

• payload - The payload containing server signature details. Can be a %ServerSignaturePayload{} struct, a JSON object, or a Base64-encoded string.
• hmac_key - The key used for HMAC calculation.

Returns:

true if the server signature is valid and matches the expected signature; otherwise, false.

---

solve_challenge/4

Description:

Attempts to solve a given challenge by searching for a number that matches the challenge criteria.

Parameters:

• challenge - The challenge string to be matched.
• salt - The salt used in challenge generation.
• algorithm - (optional) The algorithm used for hashing (:sha, :sha256, :sha512). Defaults to :sha256.
• max - (optional) The maximum number to search. Defaults to 1_000_000.
• start - (optional) The starting number for the search. Defaults to 0.

Returns:

A %Solution{} struct containing:

• :number - The number that solves the challenge.
• :took - The time taken to find the solution in milliseconds.

If no solution is found, returns nil.

License

MIT