Altcha.Plug.Challenge (Altcha v2.1.0)

Copy Markdown View Source

A Plug that serves a freshly signed ALTCHA v2 proof-of-work challenge as JSON.

Mount it wherever you want the challenge endpoint to live and point the ALTCHA widget's challengeurl at the same path.

This plug only handles GET requests; any other method passes through untouched, so it is safe to place in a shared pipeline.

Configuration

Options given where the plug is mounted take precedence over application config:

config :altcha, Altcha.Plug.Challenge,
  hmac_signature_secret: {System, :fetch_env!, ["ALTCHA_HMAC_SECRET"]}

Options

  • :hmac_signature_secret (required) - secret used to sign the challenge parameters. Accepts a string, a zero-arity function, or an {module, function, args} tuple. Functions and MFA tuples are resolved on every request, so reading the value from the environment is safe.
  • :hmac_key_signature_secret - secret for signing the pre-computed derived key. Only meaningful together with :counter (deterministic mode). Same value shapes as :hmac_signature_secret.
  • :algorithm - key derivation algorithm string, default "PBKDF2/SHA-256".
  • :cost - proof-of-work cost, default 10_000.
  • :expires_in - challenge lifetime in seconds, default 600.
  • :counter - fixed counter for deterministic challenges (advanced). A zero-arity function may be given to randomise it per request.

Usage

In a Phoenix router:

scope "/altcha" do
  forward "/challenge", Altcha.Plug.Challenge
end

As a plain Plug pipeline entry:

plug Altcha.Plug.Challenge, cost: 50_000

On the client:

<altcha-widget challengeurl="/altcha/challenge"></altcha-widget>

See the Phoenix integration guide for the full picture.