README

A lightweight PHP library for creating and verifying ALTCHA challenges using key derivation functions (PBKDF2, Argon2id, Scrypt).

Compatibility

• PHP 8.1+

Migrating from V1 to V2

• MIGRATION-v1.md

Example

• Basic Server
• Server Signature

Installation

composer require altcha-org/altcha

Usage

<?php

require 'vendor/autoload.php';

use AltchaOrg\Altcha\Altcha;
use AltchaOrg\Altcha\CreateChallengeOptions;
use AltchaOrg\Altcha\SolveChallengeOptions;
use AltchaOrg\Altcha\VerifySolutionOptions;
use AltchaOrg\Altcha\Payload;
use AltchaOrg\Altcha\Algorithm\Pbkdf2;

$pbkdf2 = new Pbkdf2();
$altcha = new Altcha(
    hmacSignatureSecret: 'secret',
    hmacKeySignatureSecret: 'key-secret', // optional, enables fast verification path
);

// Create a new challenge
// Modify the cost and counter depending on the algorithm
$challenge = $altcha->createChallenge(new CreateChallengeOptions(
    algorithm: $pbkdf2,
    cost: 5000,
    counter: random_int(5000, 10000),
    expiresAt: time() + 600,
));

// Solve the challenge (client-side in production)
$solution = $altcha->solveChallenge(new SolveChallengeOptions(
    algorithm: $pbkdf2,
    challenge: $challenge,
));

// Verify the solution (server-side)
if ($solution !== null) {
    $payload = new Payload($challenge, $solution);
    $result = $altcha->verifySolution(new VerifySolutionOptions(
        algorithm: $pbkdf2,
        payload: $payload,
    ));

    if ($result->verified) {
        echo "Solution verified!\n";
    }
}

API

Altcha

$altcha = new Altcha(
    hmacSignatureSecret: 'secret',
    hmacKeySignatureSecret: 'key-secret', // enables fast verification path
    hmacAlgorithm: HmacAlgorithm::SHA256, // default
);

Altcha::createChallenge(CreateChallengeOptions $options): Challenge

Creates a new challenge.

CreateChallengeOptions

When counter is provided and hmacKeySignatureSecret is set, the challenge includes a keySignature for fast verification (skips re-derivation).

Returns: Challenge with parameters (ChallengeParameters) and signature.

Altcha::solveChallenge(SolveChallengeOptions $options): ?Solution

Iterates counter values to find a derived key matching the challenge prefix.

SolveChallengeOptions

Returns: Solution with counter, derivedKey (hex), and time (seconds). Returns null if no match is found.

Altcha::verifySolution(VerifySolutionOptions $options): VerifySolutionResult

Verifies a solution against its challenge.

VerifySolutionOptions

VerifySolutionResult

Key Derivation Algorithms

All algorithms implement DeriveKeyInterface.

PBKDF2

use AltchaOrg\Altcha\Algorithm\Pbkdf2;
use AltchaOrg\Altcha\HmacAlgorithm;

new Pbkdf2();                        // PBKDF2/SHA-256
new Pbkdf2(HmacAlgorithm::SHA384);  // PBKDF2/SHA-384
new Pbkdf2(HmacAlgorithm::SHA512);  // PBKDF2/SHA-512

Argon2id

Requires ext-sodium (typically bundled with PHP).

use AltchaOrg\Altcha\Algorithm\Argon2id;

new Argon2id();

Uses memoryCost from challenge options.

Scrypt

Requires ext-scrypt (php-scrypt).

use AltchaOrg\Altcha\Algorithm\Scrypt;

new Scrypt();

Uses memoryCost (r, default: 8) and parallelism (p, default: 1) from challenge options.

HmacAlgorithm

Enum used for HMAC signing and PBKDF2 hash selection:

• HmacAlgorithm::SHA256 - SHA-256
• HmacAlgorithm::SHA384 - SHA-384
• HmacAlgorithm::SHA512 - SHA-512

ServerSignature::verifyServerSignature(string|array $data, string $hmacKey, HmacAlgorithm $hmacAlgorithm = HmacAlgorithm::SHA256): ServerSignatureVerification

Verifies a server signature payload.

ServerSignatureVerification

Verification data is parsed generically from URL-encoded params with auto-detected types (bool, int, float, string, array for fields/reasons). Access values via property or array syntax:

use AltchaOrg\Altcha\ServerSignature;

$result = ServerSignature::verifyServerSignature($payload, 'server-secret');

if ($result->verified) {
    $result->verificationData->expire;          // int
    $result->verificationData->score;           // float
    $result->verificationData->verified;        // bool
    $result->verificationData->fields;          // array
    $result->verificationData->classification;  // string
    $result->verificationData['email'];         // array access also works
}

ServerSignature::verifyFieldsHash(array $formData, array $fields, string $fieldsHash, HmacAlgorithm $hmacAlgorithm = HmacAlgorithm::SHA256): bool

Verifies the hash of specific form fields.

$isValid = ServerSignature::verifyFieldsHash(
    formData: ['name' => 'John', 'email' => 'john@example.com'],
    fields: ['name', 'email'],
    fieldsHash: hash('sha256', "John\njohn@example.com"),
);

Payload

Wraps a Challenge and Solution pair for verification and serialization.

$payload = new Payload($challenge, $solution);

$payload->toArray();   // array
$payload->toJson();    // JSON string
$payload->toBase64();  // base64-encoded JSON

V1 API

The V1 API is available under the AltchaOrg\Altcha\V1 namespace. It uses simple hash-based challenges (SHA-1, SHA-256, SHA-512) instead of key derivation functions.

Tests

vendor/bin/phpunit tests

License

MIT