Skip to main content
ALTCHA®

Proof-of-work

Every challenge Sentinel issues is a proof-of-work that the ALTCHA widget solves in the browser before the form can be submitted. It costs a visitor a moment of computing time and costs an automated client that time on every submission; security-group rules decide the algorithm and how much work each request gets.

How it works

Sentinel issues challenges in ALTCHA's deterministic mode:

  1. GET /v2/challenge picks a random counter from the pow.counter range and derives a key from a random nonce, salt and that counter with the chosen algorithm and cost. The challenge carries the first half of the key (keyPrefix), an HMAC of the whole key (keySignature), and is signed with the API key's secret.
  2. The widget derives keys for counters 0, 1, 2, … until one starts with keyPrefix. The work is about the counter times one derivation, split across the widget's workers.
  3. POST /v2/verify checks the signature and the HMAC of the submitted key. It doesn't derive the key again, so only the challenge endpoints pay for derivations.

A challenge verifies once, only with the API key that issued it, and only from the device that fetched it (see Verifying submissions). It expires after pow.expires, default 20m.

A security group without rules issues PBKDF2/SHA-256 challenges with cost 5000 and a counter of 1-15000. This is a light challenge for ordinary visitors; rules raise it for clients that look risky.

Algorithms

Algorithmpow.cost isDefault costDefault counterWidget solver
PBKDF2/SHA-256 (default), PBKDF2/SHA-384, PBKDF2/SHA-512Iterations50001-15000Bundled
SHA-256, SHA-384, SHA-512Hash rounds50001-1000Bundled
ARGON2IDPasses; memory is pow.memoryCost (default 65536 KiB)21-200Import separately
SCRYPTN, a power of 2; the memory is N KiB (block size 8)655361-200Import separately

PBKDF2 and SHA cost CPU time only, which GPUs and ASICs compute far faster and in parallel. ARGON2ID and SCRYPT are memory-hard: every attempt has to allocate the memory cost, which narrows the gap between a phone and specialized hardware.

When memory-hard is worth the cost

Memory-hard challenges pay off against attackers who solve challenges at scale on GPUs or solver farms, which is the usual source of high-volume automated sign-ups and form spam. They have three costs:

  • The widget needs the solver. The widget bundles only the PBKDF2 and SHA solvers. Register the ARGON2ID and SCRYPT workers under $altcha.algorithms on every page that uses the key; a widget without them can't solve the challenge. See Algorithms in the widget docs.
  • Visitors pay memory per worker. Each widget worker allocates the memory cost, so 64 MiB with 8 workers is 512 MiB. Old phones may run out of memory or take noticeably longer; the widget's retryOnOutOfMemoryError option retries with fewer workers.
  • Sentinel pays memory and CPU per challenge. Each GET /v2/challenge runs one derivation at the full cost.

If your visitors are mostly on desktops and you see solver traffic, use memory-hard challenges for every request or only for elevated ones. If many visitors use low-end phones, keep PBKDF2 as the base and switch to ARGON2ID with a modest pow.memoryCost only for risky clients.

Enabling it

Proof-of-work is always on. Two server settings limit what rules can ask for:

[pow]
max_memory_cost = 131072   # KiB: caps pow.memoryCost and scrypt N at 128 MiB (default 262144)
cpus            = 4        # derivations at once; default: half the available CPUs, at least 1

[pow] max_memory_cost (1024 to 4194304 KiB) is the largest memory one derivation may use. Rules above it are rejected when saved; rules saved under a higher cap still issue challenges, with the memory lowered to the cap. [pow] cpus (1 to 1024) caps how many challenge derivations run at once, for any algorithm; further challenges wait for a free slot. With memory-hard challenges, Sentinel's peak memory for derivations is about cpus × the memory cost. See [pow] in the Configuration reference.

Rules set everything else. This set rule moves every challenge of the group to Argon2id with 16 MiB of memory and a 5-minute lifetime:

{
  "name": "memory-hard",
  "action": "set",
  "set": [
    { "field": "pow.algorithm", "value": "ARGON2ID" },
    { "field": "pow.cost", "value": "2" },
    { "field": "pow.memoryCost", "value": "16384" },
    { "field": "pow.counter", "value": "1-400" },
    { "field": "pow.expires", "value": "5m" }
  ]
}

Add a condition, such as penalty >= 3 or risk >= 4, to apply it to risky clients only. See Writing security rules for an escalation recipe and Apply rules for saving rules in the admin UI or with the API.

The admin UI writes ready-made memory-hard rules too: check Memory-hard proof-of-work (Argon2id) on a security group's Templates tab before you apply a base preset. See Memory-hard variants for the memory and counter of each preset.

Rules & signals

Proof-of-work has no classifier rules of its own. These set fields tune it:

FieldWhat it controls
pow.algorithmThe algorithm, case-insensitive.
pow.costThe algorithm's cost: iterations, hash rounds, Argon2id passes (1–10), or scrypt N.
pow.memoryCostArgon2id memory in KiB, 1024 to [pow] max_memory_cost. Other algorithms ignore it.
pow.counterThe counter as N or a random MIN-MAX range, within 1–1000000. The main difficulty setting.
pow.expiresThe challenge lifetime, 10s to 24h.

Ranges and defaults are in the Rules reference.

Sentinel checks a pow.cost against every algorithm it can end up with, as if any combination of rules could match. A cost without a pow.algorithm in the same rule must fit the algorithms of earlier rules and the default, and a later rule that sets only pow.algorithm must accept the costs before it. A list that breaks this is rejected:

{
  "code": "INVALID_RULES",
  "error": "rules[1].set[0].value: must be an integer from 1 to 10 for ARGON2ID (pow.algorithm of rules[0]); set pow.algorithm and pow.cost in the same rule",
  "statusCode": 400
}

Set pow.algorithm and pow.cost in the same rule to avoid this.

Each verification signs the algorithm as challenge.algorithm in verificationData. Request logs record it as Proof-of-work algorithm, and Prometheus counts issued challenges in altcha_sentinel_challenges_issued_total by algorithm and protection_level.

Using the API

The widget fetches challenges itself; you call GET /v2/challenge directly only to test your rules. Use a public key. Without rules, the group issues the default challenge:

curl 'https://sentinel.example.com/v2/challenge?apiKey=key_…'
{
  "configuration": {
    "serverVerificationFields": false,
    "serverVerificationTimeZone": true,
    "verifyUrl": "/v2/verify"
  },
  "parameters": {
    "algorithm": "PBKDF2/SHA-256",
    "cost": 5000,
    "data": { "edk": "12bc56b2…", "id": "a351236c…", "issued": 1795055939725 },
    "expiresAt": 1795057139,
    "keyLength": 32,
    "keyPrefix": "0ef5cee25ca54376907743c3a4ce5221",
    "keySignature": "60137202…",
    "nonce": "f95ce641…",
    "salt": "af5a0108…"
  },
  "signature": "358ffc5e…"
}

The challenge isn't wrapped in { "data": … }, because the widget expects this shape. With the memory-hard rule above saved, the same request returns:

{
  "configuration": { … },
  "parameters": {
    "algorithm": "ARGON2ID",
    "cost": 2,
    "data": { "edk": "12bc56b2…", "id": "50d2f521…", "issued": 1795055971816 },
    "expiresAt": 1795056271,
    "keyLength": 32,
    "keyPrefix": "d0e802b9d4e1a43417c89907ffc401fb",
    "keySignature": "47a459bf…",
    "memoryCost": 16384,
    "nonce": "b86f86bf…",
    "salt": "482f3466…"
  },
  "signature": "6c10086d…"
}
  • memoryCost is omitted for PBKDF2 and SHA. For SCRYPT it is the block size, always 8, and cost is N.
  • expiresAt is in unix seconds, issued in unix milliseconds: here 300 seconds apart, from pow.expires 5m.
  • The counter isn't in the response; the widget finds it.

See GET /v2/challenge in the API reference.

Tuning

  • Raise the counter first. The counter multiplies the visitor's work directly, costs Sentinel nothing extra (it derives one key whatever the counter), and needs no widget changes. The presets escalate from the default 1-15000 to 1-30000 and 1-50000 for risky clients. A range picks a new counter for each challenge, so solve times vary.
  • Start counter ranges at 1. The widget searches from 0, but a solver that knows the minimum (from a preset, or from the counters of challenges it already solved) starts there, so MIN-MAX costs it only as much as 1-(MAX-MIN) while your visitors still pay for MIN. With 1-MAX, the longest solve stays the same and visitors and solvers alike pay about MAX/2 derivations on average. Every default and preset starts at 1.
  • Keep pow.cost at the default unless you have a reason. For PBKDF2 and SHA, the visitor's work grows with the cost as with the counter, but a higher cost also raises Sentinel's own derivation time per challenge.
  • Measure on a low-end phone. Fetch a challenge with the rule you plan and solve it in the widget on the slowest device your visitors use. Memory-hard costs that work on a desktop can fail on a phone.
  • Shorten pow.expires for login and sign-up forms (the Strict preset uses 5m), so solved challenges can't be stockpiled. Keep it longer than the time a visitor needs to fill in the form, or the submission fails with CHALLENGE_EXPIRED.
  • Combine it with rate limits. Proof-of-work slows each request but doesn't cap them. Add rateLimit.limits (see Rate limiting & penalty), which also protects Sentinel's CPU from challenge floods.
  • Size [pow] cpus for your traffic. With memory-hard algorithms, a burst of challenges queues for the derivation slots. Raise cpus on a dedicated host, or lower max_memory_cost to bound memory.

Monitor mode doesn't help with set rules here: a monitored rule's settings aren't applied, so its challenge stays unchanged. Test a new rule on a separate key and security group instead.

Limitations

  • Proof-of-work raises the cost of each submission; it doesn't detect bots. An attacker who pays the cost gets through, so combine it with the classifier, Human Interaction Signature and rate limits.
  • Memory-hard algorithms work only with widgets that load their solvers. Native apps and custom clients need an Argon2id or scrypt implementation too.
  • Only widget v3 and later are supported; legacy SHA challenges from widgets 2.x and earlier get 400 INVALID_PAYLOAD.
  • Sentinel derives one key per challenge, so challenge floods cost it CPU, and with memory-hard algorithms memory. [pow] cpus bounds the cost, at the price of queued challenges.

Start typing to search...

↑ ↓ Navigate ↵ Select