Instrukcja wdrożenia

Wdrożenie KODOPOL CAPTCHA wymaga implementacji dwóch podstawowych elementów:

• Wywołanie popupu CAPTCHA na froncie
• Weryfikacja zwrotki z CAPTCHA na backendzie

Wywołanie popupu CAPTCHA

Można skorzystać z naszego skryptu (wkleić go bezpośrednio do kodu strony) lub przygotować własną implementację. Skrypt można wygenerować w tym panelu w zakładce Generator. Dodatkowo na stronie, na której wklejamy skrypt, musimy zaimplementować formularz z inputem kodopol_captcha. Skrypt wpina się w taki formularz oraz przechwytuje próbę jego wysłania, wywołując popup z KODOPOL CAPTCHA. Po rozwiązaniu CAPTCHA przez użytkownika formularz jest wysyłany, a backend otrzymuje zwrotkę z danymi oraz polem kodopol_captcha.

<form method="POST">
    <input type="hidden" name="kodopol_captcha">
    <button>
        Wyślij
    </button>
</form>
<script>
    const input = document.querySelector('form input[name="kodopol_captcha"]');
    const form = input.closest('form');
    form.addEventListener('submit', (e) => {
        e.preventDefault();
        window.open(`https://captcha.kodopol.eu/captcha?org=captcha.kodopol.eu&own=captcha@kodopol.eu&ref=${location.origin}`, 'kodopol_captcha', 'width=500,height=700');
    })
    window.addEventListener('message', (event) => {
        const { kodopol_captcha } = event.data;
        input.value = kodopol_captcha;
        form.submit();
    });
</script>

Parametry zapytania do /captcha:

Parametr	Nazwa	Opis
org	Domena	Nazwa domeny aplikacji, która korzysta z CAPTCHA
own	Właściciel	Adres e-mail konta, które wygenerowało klucz prywatny
ref*	Odpowiedź	Adres strony, która wywołała popup CAPTCHA

Backend: weryfikacja zwrotki

Po wygenerowaniu klucza kodopol_captcha formularz zostaje przesłany do backendu. Tam możemy go przechwycić (w przypadku PHP) $_POST['kodopol_captcha'], a następnie przy pomocy biblioteki SIGIL zweryfikować autentyczność odpowiedzi:

if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    $token = $_POST['kodopol_captcha'] ?? '';
    $check = sigil_check($token, "captcha@kodopol.eu|captcha.kodopol.eu", 'PRIVATE_KEY', 30);
    if ($check['ok']) {
        /** @TODO: */
    }
}

Zwrotka jest po prostu ciągiem znaków ADRES_EMAIL_WŁAŚCICIELA|DOMENA_APLIKACJI, sygnaturowanym SIGIL-em przy pomocy klucza prywatnego właściciela w przedziale czasowym 2×30 s. Bibliotekę SIGIL można znaleźć na stronie KODOPOL lub użyć poniższego kodu:

function sigil_hash (string $str, string $priv) : string
{
    return hash_hmac('sha512', $str, $priv);
}

function sigil_check (string $sigil, string $code, string $priv, int $time_frame) : array
{
    $current_time_frame = floor(time() / $time_frame);
    $hash = sigil_hash($code . '|' . $current_time_frame, $priv);

    if (hash_equals($sigil, $hash)) {
        return [
            'ok' => true,
            'expr' => false
        ];
    }

    $past_time_frame = floor((time() - $time_frame) / $time_frame);
    $hash2 = sigil_hash($code . '|' . $past_time_frame, $priv);
    if (hash_equals($sigil, $hash2)) {
        return [
            'ok' => true,
            'expr' => true,
            'rehash' => $hash
        ];
    }

    return [
        'ok' => false
    ];
}

function sigil_sign (string $code, string $priv, int $time_frame) : string
{
    $current_time_frame = floor(time() / $time_frame);
    $hash = sigil_hash($code . '|' . $current_time_frame, $priv);
    return $hash;
}

Dzięki bibliotece SIGIL jesteśmy w stanie zweryfikować, że to faktycznie serwer captcha.kodopol.eu potwierdził wykonanie CAPTCHA. Jeżeli hash zwrócony na backendzie odpowiada hashowi wygenerowanemu przez backend przy użyciu klucza prywatnego, oznacza to, że tylko serwer KODOPOL mógł wygenerować tę zwrotkę.

Biblioteka SIGIL może wydawać się na pierwszy rzut oka skomplikowana, ale w rzeczywistości jest bardzo prosta i stanowi podstawę oraz nieodzowny fundament większości interfejsów programistycznych KODOPOL.