Caddy

The module for Caddy puts a challenge in front of each request. A visitor who passes it gets a signed session cookie and goes to your application without a subsequent interruption until the time limit expires. The module redirects all other requests to the challenge page.

Thus, the protection applies to the full domain, not to individual forms.

Sequence

1. The module examines each request for a valid session cookie with an HMAC signature that is bound to the IP address.
2. Without a valid cookie, it redirects the request to the path of the challenge.
3. After the challenge passed, the module verifies the token on the server with the API.
4. If the verification is successful, it sets the signed cookie and redirects to the initial address.

Requirements

The following requirements must be met:

Requirement	Value
Caddy	From version 2.9
Tool	xcaddy to build with the module
Go	From version 1.22 to build from the sources
Credentials	Public sitekey and secret from the Details view

Build Caddy with the module

Build Caddy with xcaddy:

xcaddy build --with github.com/Myra-Security-GmbH/eu-captcha-caddy

Build from the sources as follows:

git clone https://github.com/Myra-Security-GmbH/eu-captcha-caddy.git
cd eu-captcha-caddy
xcaddy build --with github.com/Myra-Security-GmbH/eu-captcha-caddy=.

Set up the module

Add these entries to the Caddyfile file:

example.com {
    eu_captcha {
        sitekey        EUCAPTCHA_SITE_KEY
        secret         EUCAPTCHA_SECRET_KEY
        cookie_secret  <random-32-byte-hex>   # openssl rand -hex 32
        grace_period   1h
    }

    reverse_proxy localhost:3000
}

In the configuration as JSON, the entry is as follows:

{
  "handler": "eu_captcha",
  "sitekey": "EUCAPTCHA_SITE_KEY",
  "secret": "EUCAPTCHA_SECRET_KEY",
  "cookie_secret": "<random-32-byte-hex>",
  "grace_period": "1h"
}

Settings

These settings are available:

Setting	Necessary	Default	Effect
sitekey	yes	—	Public sitekey.
secret	yes	—	Secret key.
cookie_secret	yes	—	Key for the HMAC signature of the session cookies. Make it with openssl rand -hex 32.
grace_period	no	1h	Validity period of a passed challenge as a time value in the format of Go.
cookie_name	no	__eucaptcha	Name of the session cookie.
challenge_path	no	/__captcha__	Start of the path for the challenge and for the verification.
verify_url	no	https://api.eu-captcha.eu/v1/verify	Address of the endpoint for the verification of the token.
credentials_check_url	no	https://api.eu-captcha.eu/v1/verify-credentials	Address of the endpoint for the verification of the credentials. The module calls it at the start.

Reserved paths

The module reserves two paths of your domain. Do not use these paths in your application:

Path	Use
{challenge_path}	Shows the challenge page.
{challenge_path}/verify	Accepts the solved token with POST.

With the default value for challenge_path, these are the /__captcha__ and /__captcha__/verify paths.