Ixnas.AltchaNet 1.1.0

Altcha.NET

C# implementation of the ALTCHA challenge.

Features

• Compatible with the ALTCHA client-side widget
• Independent from ASP.NET (Core)
• Generates and validates self-hosted challenges
• Validates challenges from ALTCHA's public API
• Validates forms that were spam-filtered by ALTCHA's spam filter API
• Solves remotely hosted challenges, enabling machine-to-machine ALTCHA
• Replay attack prevention by denying previously verified challenges
• Expiring challenges

Contents

• Installation
• Using self-hosted challenges
  • Set up
    • Key
    • Store
  • Usage
    • Generating a challenge
    • Validating a response
• Verifying challenges from ALTCHA's API
  • Set up
  • Usage
    • Validating a regular response
    • Validating a spam filtered form
• Solving challenges
  • Set up
  • Usage
• Example
• Contributing
• License

Installation

This library is available on NuGet, so you can add it to your project as follows:

dotnet add package Ixnas.AltchaNet

Using self-hosted challenges

Set up

First make sure you've set up the front-end widget to use your challenge endpoint.

The entrypoint of this library contains a service builder for self-hosted configurations. This builder configures the service that is used to create ALTCHA challenges and validate their responses. The most basic configuration looks like this:

var altchaService = Altcha.CreateServiceBuilder()
                          .UseSha256(key)
                          .UseStore(storeFactory)
                          .Build();

Here is a description of the different configuration options.

Key

The library requires a key to sign and verify ALTCHA challenges. You can use a random number generator from .NET to create one for you:

var key = new byte[64];
using (var rng = RandomNumberGenerator.Create())
{
    rng.GetBytes(key);
}

Store

The library requires a store implementation to store previously verified challenge responses. You can use anything persistent, like a database or a file. As long as it implements the IAltchaChallengeStore or the IAltchaCancellableStore interface, it will work.

For persistent (I/O-bound) storage implementations, you should probably implement IAltchaCancellableStore which supports CancellationTokens.

You can use expiryUtc to periodically remove expired challenges from your store.

As an example, the bundled in-memory store looks similar to this:

public class InMemoryStore : IAltchaChallengeStore
{
    private class StoredChallenge
    {
        public string Challenge { get; set; }
        public DateTimeOffset ExpiryUtc { get; set; }
    }

    private readonly List<StoredChallenge> _stored = new List<StoredChallenge>();

    public Task Store(string challenge, DateTimeOffset expiryUtc)
    {
        var challengeToStore = new StoredChallenge
        {
            Challenge = challenge,
            ExpiryUtc = expiryUtc
        };
        _stored.Add(challengeToStore);
        return Task.CompletedTask;
    }

    public Task<bool> Exists(string challenge)
    {
        _stored.RemoveAll(storedChallenge => storedChallenge.ExpiryUtc <= DateTimeOffset.UtcNow);
        var exists = _stored.Exists(storedChallenge => storedChallenge.Challenge == challenge);
        return Task.FromResult(exists);
    }
}

If you're using a short-lived object to access your database (like a request-scoped Entity Framework DbContext), it is recommended to provide a factory function for the store instead of an instance.

Usage

Generating a challenge

To generate a challenge:

var challenge = altchaService.Generate();

The challenge object can be serialized to JSON for the client to use. Read ALTCHA's documentation on how to use such a JSON object.

It's possible to override configuration options by passing an AltchaGenerateChallengeOverrides object. This can be useful when implementing a dynamic complexity strategy, for example.

var overrides = new AltchaGenerateChallengeOverrides
{
    Complexity = new AltchaComplexity(200000, 300000),
    Expiry = new AltchaExpiry(300),
};
var challenge = altchaService.Generate(overrides);

Only the properties that are set will affect the generation, and only for this single call.

Validating a response

To validate a response:

var validationResult = await altchaService.Validate(altcha, cancellationToken);
if (!validationResult.IsValid)
{
    _logger.LogInformation(validationResult.ValidationError.Message);
    /* ... */
}

The altcha parameter can either be a base64-encoded JSON string (like the raw value of the altcha field in a submitted form), or an already decoded and deserialized AltchaResponse object.

The cancellationToken parameter can be passed if the service was set up with a IAltchaCancellableChallengeStore. The cancellation token can cancel queries and updates to the store implementation.

Verifying challenges from ALTCHA's API

Set up

First make sure you've set up the front-end widget to use the API.

The entrypoint of this library contains a different service builder for integrating with ALTCHA's API. The most basic configuration looks like this:

var altchaApiService = Altcha.CreateApiServiceBuilder()
                             .UseApiSecret(secret)
                             .UseStore(storeFactory)
                             .Build();

Here is a description of the different configuration options.

The store uses the same interface as it does for the self-hosted service. You can even use the same instance if you like.

Usage

Validating a regular response

To validate a regular response:

var validationResult = await altchaApiService.Validate(altcha, cancellationToken);
if (!validationResult.IsValid)
{
    _logger.LogInformation(validationResult.ValidationError.Message);
    /* ... */
}

This works the same way as self-hosted validation. Challenges generated by the self-hosted service can not be validated by the API service, or vice versa.

Validating a spam filtered form

To validate a spam filtered form, you need an object that represents the form fields as public string properties. By default, the library looks for a public string property named Altcha that should contain the raw value from the altcha field in a submitted form. A form class could look like this:

public class ExampleForm
{
    public string Altcha { get; set; }
    public string Email { get; set; }
    public string Text { get; set; }
}

To validate the form:

var validationResult = await altchaApiService.ValidateSpamFilteredForm(form, cancellationToken);
if (!validationResult.IsValid)
{
    _logger.LogInformation(validationResult.ValidationError.Message);
    /* ... */
}

if (!validationResult.PassedSpamFilter)
    /* ... */

If you prefer to use a different property for the ALTCHA payload, you can use a member expression to select it:

var validationResult = await altchaApiService.ValidateSpamFilteredForm(form, cancellationToken, x => x.AnotherProperty);

The result's IsValid property tells you whether the form data, verification data and the signature are valid. You should probably reject the form submission if this is not the case. The ValidationError property contains more details on why the validation failed.

The result's PassedSpamFilter property tells you whether the form data successfully passed through the spam filter. You might want to keep the form submission and mark it as spam in your application for manual approval.

Solving challenges

Set up

The entrypoint of this library contains a builder for creating solver instances. The most basic configuration looks like this:

var altchaSolver = Altcha.CreateSolverBuilder()
                         .Build();

Here is a description of the different configuration options.

Usage

To solve a challenge, first make sure you have a deserialized AltchaChallange object to solve. Then you can solve the challenge as follows:

var solverResult = altchaSolver.Solve(challenge);

if (!solverResult.Success)
{
    _logger.LogInformation(solverResult.Error.Message);
    /* ... */
}

var formWithAltcha = new
{
    SomeFormField = "some text",
    Altcha = solverResult.Altcha
};

This example attaches the solution from solverResult.Altcha to a form object as the "altcha" field.

Example

The AspNetCoreExample project contains a few examples for generating, solving and validating challenges.

Contributing

Bug reports, fixes, ideas and suggestions are always welcome! Feel free to reach out by creating new issues, and I'll try to respond as soon as I can.

License

See LICENSE.txt

See LICENSE-ALTCHA.txt for ALTCHA's original license.