LibreCaptcha

LibreCaptcha is a framework that allows developers to create their own CAPTCHAs. The framework defines the API for a CAPTCHA generator and takes care of mundane details such as:

• An HTTP interface for serving CAPTCHAs
• Background workers to pre-compute CAPTCHAs and to store them in a database
• Managing secrets for the CAPTCHAs (tokens, expected answers, etc)
• Safe re-impressions of CAPTCHA images (by creating unique tokens for every impression)
• Garbage collection of stale CAPTCHAs
• Sandboxed plugin architecture (TBD)

Some sample CAPTCHA generators are included in the distribution (see below). We will continue adding more samples to the list. For quick deployments the samples themselves might be sufficient. Projects with more resources might want create their own CAPTCHAs and use the samples as inspiration. See the CAPTCHA creation guide.

Current Status

The framework is stable, but since it is our first public release, we recommend using it only on small to medium scale web apps.

The sample CAPTCHAs are also just that, samples. They have not been tested against bots or CAPTCHA crackers yet.

Quick start with Java

1. Download the jar file from the latest release
2. Type mkdir data/. (The data directory is used to store a config file that you can tweak, and for storing the Database)
3. Type java -jar LibreCaptcha.jar
4. Open localhost:8888/demo/index.html in browser

We recommend a Java 11+ runtime as that's what we compile the code with.

Alternatively,

1. Install sbt
2. Clone this repository
3. Type sbt run within the repository
4. Open localhost:8888/demo/index.html in browser

Quick start with Docker

Using docker-compose:

git clone https://github.com/librecaptcha/lc-core.git
docker-compose up

Using docker:

docker run -p=8888:8888 -v ./lcdata:/lc-core/data librecaptcha/lc-core:2.0

A default config.json is automatically created in the mounted volume.

The above commands should work with podman as well, if docker.io registry is pre-configured. Otherwise, you can manually specify the repository like so:

podman run -p=8888:8888 -v ./lcdata:/lc-core/data docker.io/librecaptcha/lc-core:2.0

Quick test

Open localhost:8888/demo/index.html in browser.

Alternatively, on the command line, try:

> $ curl -d '{"media":"image/png","level":"easy","input_type":"text","size":"350x100"}' localhost:8888/v2/captcha
{"id":"3bf928ce-a1e7-4616-b34f-8252d777855d"}

> $ curl "localhost:8888/v1/media?id=3bf928ce-a1e7-4616-b34f-8252d777855d" -o sample.png

> $ file sample.png
sample.png: PNG image data, 350 x 100, 8-bit/color RGB, non-interlaced

The API endpoints are described at the end of this file.

Configuration

If a config.json file is not present in the data/ folder, the app creates one, and this can be modified to customize the app features, such as which CAPTCHAs are enabled and their difficulty settings.

More details can be found in the wiki

Why LibreCaptcha?

Eliminate dependency on a third-party

An open-source CAPTCHA framework will allow anyone to host their own CAPTCHA service and thus avoid dependencies on third-parties.

Respecting user privacy

A self-hosted service prevents user information from leaking to other parties.

More variety of CAPTCHAs

Ain't it boring to identify photos of buses, store-fronts and traffic signals? With LibreCaptcha, developers can create CAPTCHAs that suit their application and audience, with matching themes and looks.

And, the more the variety of CAPTCHAS, the harder it is for bots to crack CAPTCHAs.

Sample CAPTCHAs

These are included in this server.

ShadowText

FilterCaptcha

An image of a random string of alphabets is created. Then a series of image filters that add effects such as Smear, Diffuse, and Ripple are applied to the image to make it less readable.

RainDropsCaptcha

PoppingCharactersCaptcha

LabelCaptcha

This CAPTCHA provider takes in two sets of images. One with known labels, and the other unknown. The created image has a pair of words one from each set. The user is tested on the known word, and their answer to the unknown word is recorded. If a sufficient number of users agree on their answer to the unknown word, it is transferred to the list of known words.

(There is a known issue with this provider; see issue #68 )

---

HTTP API

The service can be accessed using a simple HTTP API.

- /v1/captcha: POST

• Parameters:

  • level: String - The difficulty level of a captcha
    • easy
    • medium
    • hard
  • input_type: String - The type of input option for a captcha
    • text
    • (More to come)
  • media: String - The type of media of a captcha
    • image/png
    • image/gif
    • (More to come)
  • size: String - The dimensions of a captcha. It needs to be a string in the format "widthxheight" in pixels, and will be matched with the allowedSizes config setting. Example: size: "450x200" which requests an image of width 450 and height 200 pixels.

• Returns:

  • id: String - The uuid of the captcha generated

- /v1/media: GET

• Parameters:

  • id: String - The uuid of the captcha

• Returns:

  • image: Array[Byte] - The requested media as bytes

- /v1/answer: POST

• Parameter:

  • id: String - The uuid of the captcha that needs to be solved
  • answer: String - The answer to the captcha that needs to be validated

• Returns:

  • result: String - The result after validation/checking of the answer
    • True - If the answer is correct
    • False - If the answer is incorrect
    • Expired - If the time limit to solve the captcha exceeds

Example usage

In javascript:

const resp = await fetch("/v2/captcha", {
    method: 'POST',
    body: JSON.stringify({level: "easy", media: "image/png", "input_type" : "text", size: "350x100"})
})

const respJson = await resp.json();

let captchaId = null;

if (resp.ok) {
    // The CAPTCHA can be displayed using the data in respJson.
    console.log(respJson);
    // Store the id somewhere so that it can be used later for answer verification
    captchaId = respJson.id;
} else {
    console.err(respJson);
}


// When user submits an answer it can be sent to the server for verification thusly:
const resp = await fetch("/v2/answer", {
    method: 'POST',
    body: JSON.stringify({id: captchaId, answer: "user input"})
});
const respJson = await resp.json();
console.log(respJson.result);

---

Roadmap

Things to do in the future:

• Sandboxed plugin architecture
• Audio CAPTCHA samples
• Interactive CAPTCHA samples