Important: domain name change. We are moving from web-utils.eu to securecaptcha.net. If you use our service, change host name in your code.

Secure CAPTCHA - installation, configuration, API and code samples

This page contains technical information about integrating the Secure CAPTCHA inside the HTML or XHTML form.

Overview

Secure CAPTCHA, when integrated into online form, allows to distinguish between form submition made by human and machine (robot, bot, script, program, etc.).

On this page, we accept following convention.

CAPTCHA service is our service at http://www.securecaptcha.net.
Server is your HTTP server that creates the HTML/XHTML forms with CAPTCHA images.
User is an entity you want to examine on being the human.
Question is shown to the user. It is an image of few handwritten letters.
Answer is submitted by user. Correct answer is a same text as the question.

To integrate Secure CAPTCHA with your server, you will have to complete following steps:
1. Configuration
2. Embedding question into the HTML/XHTML form
3. Validating the answer
3a. Offline validation
3a. Online validation

1. Configuration

We assume, that you have already created account at SecureCAPTCHA.net, added a site and obtained your siteID and privateKey.

2. Embedding questions into the form

To insert CAPTCHA element into your form you must insert a special peace of code into your form serving function (or wherever else you want). That peace of code will make a challenge request. Challenge request is a HTTP request to the address http://www.securecaptcha.net/captcha/generateResponse with following parameters:

hash - some randomly generated key, used to validate the challenge response,
auth - your siteID (you should obtain it after signing up and creating a site definition on SecureCAPTCHA.net).

Response contains the following (lines are divided with \n character):

mac (in first line) - long key used for offline validation,
timestamp (in second line) - time stamp of the challenge is seconds after 1st Jan 1970,
fragment (in next lines) - HTML/XHTML fragment you should put into your page.

Hash, mac and timestamp values will be used for a challenge response validation. You must store them in some way to reload them upon the form submition. It is better not to reveal them to the end-user, so do not put them in the form hidden values. User session object is a good place for them, if your session implementation is secure.

You should print fragment directly to your page (perhaps with appropriate encoding transform). Do not try to assume any structure of the fragment. It may change in the future.

You must put fragment in such place on your page, that it will be visible to the user. You may assign custom CSS styles, but you must ensure that every part of the fragment is easily visible to the user. CAPTCHA image looks better with border (ie. 1px solid black). You may surround CAPTCHA fragment with <div class="captchaContainer"></div> and define CSS rule .captchaContainer img {border: 1px solid black; } .

Here you can find example scripts doing the challenge request written in some commonly used programming languages.

Show python code

Python

You need handwrittenCaptcha.py to run this code.


from handwrittenCaptcha import CaptchaService

# this is your siteID
siteID = 'put here your siteID!'
# this is your privateKey
privateKey = 'put here your privateKey!'

captchaService = CaptchaService(siteID, privateKey)

(status, value) = captchaService.getCaptcha())
if status:
    # there was no error
    (hsh, mac, timestamp, fragment) = value
    # we put data into user's session object
    session['captchaData'] = (hsh, mac, timestamp)
    # we print the HTML/XHTML fragment with captcha
    print fragment
    print 'Rewrite letters from the image above (lower Latin letters only): '
    print ''
else:
    # there was an error, we simply print error info
    print 'Error occurred: %s' % value


# In above example we assumed, that:
#   session is your session object,
#   print prints into HTTP response.
# You may need to change this depending on your HTTP engine/library/framework.

Show Java code

Java

You need handwrittenCaptcha.jar to run this code.


import net.securecaptcha.captcha.CaptchaService;
import net.securecaptcha.captcha.CaptchaService.CaptchaData;
import net.securecaptcha.captcha.CaptchaService.CaptchaException;
import net.securecaptcha.captcha.CaptchaService.CaptchaTO;

//...

    // your siteID
    public static final String siteID = "put here your siteID!";
    // your privateKey
    public static final String privateKey = "put here your privateKey!";

//...

        // initialization of CaptchaService
        CaptchaService captchaService = new CaptchaService(siteID, privateKey);

        try {
            // create new captcha
            CaptchaTO captchaTO = captchaService.getCaptcha();
            // save captcha data
            session.setAttribute("captchaData", captchaTO.data);
            // print captcha
            out.println(captchaTO.fragment);
            out.println("Rewrite the text above (only lower Latin letters). ");
            out.println("<input type=\"text\" name=\"answer\">");
        } catch (CaptchaException e) {
            out.println("Captcha error: " + e.getMessage());
        }


# In above example we assumed, that: 
#   session is your session object
#   out is your HTTP response writer

Show PHP code

PHP

You need handwrittenCaptcha.php to run this code.


require 'handwrittenCaptcha.php';

$siteID = 'Put here your siteID!';
$privateKey = 'Put here your privateKey!';
$captchaService = new CaptchaService($siteID, $privateKey);

if ($captchaService->getCaptcha($value)) {
    $hash = $value['hash'];
    $mac = $value['mac'];
    $timestamp = $value['timestamp'];
    $fragment = $value['fragment'];
    $_SESSION['captchaData'] = array('hash' => $hash, 'mac' => $mac, 'timestamp' => $timestamp);
    echo $fragment;
    echo 'Rewrite letters from the image above (lower Latin letters only): ';
    echo '';
} else {
    echo 'An error occurred: ' . $value;
}

3. Validating the answer

Upon form submition you should make validation to check, whether the answer submitted by the user is correct. To make a validation, you should know hash, mac and timestamp generated in step 2. You should also have the answer submitted by the user.

Before validation you may reject some submitions comparing timestamp value with current time and reject this submitions that has been solved longer then some time (ie. 3 minutes). Before implementing that, ensure, that your server clock time is accurate. If not, you may provide your own timestamp checking.

There are two ways of validation: offline (takes place on your server, requires md5 digest computation) and online (by a HTTP request).

3a. Offline validation

Note, that you may perform an offline validation only if you are sure, that hash value used in this step is the same value that been generated by you in step 2. You can not use offline validation ie. if hash has been generated on the client side (Java Script).

To make offline validation calculate hmac with key=privateKey, message=hash+answer+timestamp (+ is a string concatenation), digestAlgorithm=md5, oped=0x5C, ipad=0x36. If result as a lower hex string is equal to the mac, user has entered a correct answer.

Before making offline validation, you should check timestamp value. If your system clock is not accurate, you should provide your own timestamp checking or perform online validation.

Here you can find example scripts doing the challenge request written in some commonly used programming languages.

Show python code

Python

You need handwrittenCaptcha.py to run this code.


from handwrittenCaptcha import CaptchaService

# this is your siteID
siteID = 'put here your siteID!'
# this is your privateKey
privateKey = 'put here your privateKey!'

captchaService = CaptchaService(siteID, privateKey)

sessionData = session.get('captchaData', None)
if not sessionData:
    print 'No session data. Enable cookies. '
else:
    (hsh, mac, timestamp) = sessionData
    answer = str(request.get('answer', ''))

    del session['captchaData']

    isValid = captchaService.validateOffline(hsh, mac, timestamp, answer) 
    if isValid: 
        print 'OK, human. '
    else:
        print 'May be not a human. '


# In above example we assumed, that:
#   session is your session object,
#   request is your request object,
#   print prints into HTTP response.
# You may need to change this depending on your HTTP engine/library/framework.

Show Java code

Java

You need handwrittenCaptcha.jar to run this code.


import net.securecaptcha.captcha.CaptchaService;
import net.securecaptcha.captcha.CaptchaService.CaptchaData;
import net.securecaptcha.captcha.CaptchaService.CaptchaException;
import net.securecaptcha.captcha.CaptchaService.CaptchaTO;

// ...

    // your siteID
    public static final String siteID = "put here your siteID!";
    // your privateKey
    public static final String privateKey = "put here your privateKey!";

// ... 

        // initialization of CaptchaService
        CaptchaService captchaService = new CaptchaService(siteID, privateKey);

        String answer = req.getParameter("answer");
        if (answer != null) {
            // restore captcha data
            CaptchaData data = (CaptchaData)session.getAttribute("captchaData");
            if (data == null) {
                out.println("No session data. Enable cookies. ");
            } else {

                session.removeAttribute("captchaData");

                // offline validation
                if (captchaService.validateOffline(data, answer)) {
                    out.println("OK, human. ");
                } else {
                    out.println("May be not a human. ");
                }
            }
        } 


# In above example we assumed, that:
#   session is your session object
#   out is your HTTP response writer

Show PHP code

PHP

You need handwrittenCaptcha.php to run this code.


require 'handwrittenCaptcha.php';

$siteID = 'Put here your siteID!';
$privateKey = 'Put here your privateKey!';
$captchaService = new CaptchaService($siteID, $privateKey);

$answer = $_REQUEST['answer'];
$value = $_SESSION['captchaData'];
$hash = $value['hash'];
$mac = $value['mac'];
$timestamp = $value['timestamp'];

unset($_SESSION['captchaData']);

$okOffline = $captchaService->validateOffline($hash, $mac, $timestamp, $answer);
if ($okOffline) {
    print 'Offline validation: OK. 
';
}

3b. Online validation

To make online validation, make HTTP request to the http://www.securecaptcha.net/captcha/validate with following parameters:

auth - your siteID,
hash - hash value generated in step 2,
timestamp - timestamp value obtained in step 2,
code - answer submitted by the user.

Received response contains the following (lines are separated with \n):

status (in first line) - integer value,
reason (in second line) - description of status.

If status is 1, answer is correct and you may assume, that form has been submitted by a human.

Here you can find example scripts doing the challenge request written in some commonly used programming languages.

Show python code

Python

You need handwrittenCaptcha.py to run this code.


from handwrittenCaptcha import CaptchaService

# this is your siteID
siteID = 'put here your siteID!'
# this is your privateKey
privateKey = 'put here your privateKey!'

captchaService = CaptchaService(siteID, privateKey)

sessionData = session.get('captchaData', None)
if not sessionData:
    print 'No session data. Enable cookies. '
else:
    (hsh, mac, timestamp) = sessionData
    answer = str(request.get('answer', ''))
    (status, value) = captchaService.validateOnline(hsh, timestamp, answer)
    if status:
        if value:
            print 'OK, human. '
       else:
            print 'May be not a human. '
    else:
        print 'Error occurred: %s' % value


# In above example we assumed, that:
#   session is your session object,
#   request is your request object,
#   print prints into HTTP response.
# You may need to change this depending on your HTTP engine/library/framework.

Show Java code

Java

You need handwrittenCaptcha.jar to run this code.


import net.securecaptcha.captcha.CaptchaService;
import net.securecaptcha.captcha.CaptchaService.CaptchaData;
import net.securecaptcha.captcha.CaptchaService.CaptchaException;
import net.securecaptcha.captcha.CaptchaService.CaptchaTO;

// ...

    // your siteID
    public static final String siteID = "put here your siteID!";
    // your privateKey
    public static final String privateKey = "put here your privateKey!";

// ...

        // initialization of CaptchaService
        CaptchaService captchaService = new CaptchaService(siteID, privateKey);

        String answer = req.getParameter("answer");
        if (answer != null) {
            // restore captcha data
            CaptchaData data = (CaptchaData)session.getAttribute("captchaData");
            if (data == null) {
                out.println("No session data. Enable cookies. ");
            } else {

                try {
                    // online validation
                    if (captchaService.validateOnline(data, answer)) {
                        out.println("OK, human. ");
                    } else {
                        out.println("May be not a human. ");
                    }
                } catch (CaptchaException e) {
                    out.println("Validation error: " + e.getMessage());	
                }

            }
        }


# In above example we assumed, that:
#   session is your session object
#   out is your HTTP response writer

Show PHP code

PHP

You need handwrittenCaptcha.php to run this code.


require 'handwrittenCaptcha.php';

$siteID = 'Put here your siteID!';
$privateKey = 'Put here your privateKey!';
$captchaService = new CaptchaService($siteID, $privateKey);

$answer = $_REQUEST['answer'];
$value = $_SESSION['captchaData'];
$hash = $value['hash'];
$mac = $value['mac'];
$timestamp = $value['timestamp'];

$okOnline = $captchaService->validateOnline($hash, $timestamp, $answer, $error);
if ($okOnline) {
    print 'Online validation: OK. 
';
}
if ($error != null) {
    print 'Online validation error: ' . error . '
';
}