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:
GET /v2/challengepicks a random counter from thepow.counterrange 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.- 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. POST /v2/verifychecks 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
| Algorithm | pow.cost is | Default cost | Default counter | Widget solver |
|---|---|---|---|---|
PBKDF2/SHA-256 (default), PBKDF2/SHA-384, PBKDF2/SHA-512 | Iterations | 5000 | 1-15000 | Bundled |
SHA-256, SHA-384, SHA-512 | Hash rounds | 5000 | 1-1000 | Bundled |
ARGON2ID | Passes; memory is pow.memoryCost (default 65536 KiB) | 2 | 1-200 | Import separately |
SCRYPT | N, a power of 2; the memory is N KiB (block size 8) | 65536 | 1-200 | Import 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
ARGON2IDandSCRYPTworkers under$altcha.algorithmson 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
retryOnOutOfMemoryErroroption retries with fewer workers. - Sentinel pays memory and CPU per challenge. Each
GET /v2/challengeruns 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:
| Field | What it controls |
|---|---|
pow.algorithm | The algorithm, case-insensitive. |
pow.cost | The algorithm's cost: iterations, hash rounds, Argon2id passes (1–10), or scrypt N. |
pow.memoryCost | Argon2id memory in KiB, 1024 to [pow] max_memory_cost. Other algorithms ignore it. |
pow.counter | The counter as N or a random MIN-MAX range, within 1–1000000. The main difficulty setting. |
pow.expires | The 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…"
}memoryCostis omitted for PBKDF2 and SHA. ForSCRYPTit is the block size, always8, andcostis N.expiresAtis in unix seconds,issuedin unix milliseconds: here 300 seconds apart, frompow.expires5m.- 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-15000to1-30000and1-50000for 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-MAXcosts it only as much as1-(MAX-MIN)while your visitors still pay forMIN. With1-MAX, the longest solve stays the same and visitors and solvers alike pay aboutMAX/2derivations on average. Every default and preset starts at 1. - Keep
pow.costat 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.expiresfor login and sign-up forms (the Strict preset uses5m), 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 withCHALLENGE_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] cpusfor your traffic. With memory-hard algorithms, a burst of challenges queues for the derivation slots. Raisecpuson a dedicated host, or lowermax_memory_costto 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] cpusbounds the cost, at the price of queued challenges.
Related
pow.*set fields in the Rules reference[pow]in the Configuration reference- Memory-hard variants of the security presets
- Code challenge
- Widget integration and the widget's algorithm workers
- Verifying submissions