Aeolus - Deliverable D6.2.10 - New Components for the Overlay Computing Platform - Secure CAPTCHA (sCAPTCHA)


CONTENTS
========

* License
* System Requirements
* Introduction
* Directory Structure
* Usage and Installation
* Building instructions
* AEOFORGE

License
=======

The software is licensed under the GPL, please see the gpl-3.0.txt file for more information.


System Requirements
===================

sCAPTCHA requires JDK6 or higher. You can download it at http://java.sun.com/
The Firefox plugin requires at least Firefox 3.0


Introduction
============

A denial of service attack (DOS) is an attack against a network service where an
adversary abuses a service in such a way that it becomes unusable for other users.
When the attack is driven by a large number of  machines distributed over the network, it is
called distributed DOS (DDOS).

To combat a DDOS, a web server can introduce a barrier between the service and the
users. Only resolving a puzzle it is possible to gain access to the service.
A common used puzzle is the CAPTCHA which is an image with distorted text.
The user is asked to extract the distorted text from the image and supply this
information in a form. Only if the user has supplied the right text she gains access to
the service. This task is very hard for computer programs.

A man in the middle attack can be mounted against the CAPTCHA. Suppose
that an attacker wants to break www.site.com which is protected with CAPTCHAs.
The attackers can build a new site www.freestuff.com with lots of free and valuable stuff.
Every time a user goes to www.freestuff.com, the attacker gets a CAPTCHA from www.site.com
and submits it to the user. The solution provided by the user can then be used to
access www.site.com;

Secure CAPTCHA provides the following enhances:
- it includes in the CAPTCHA the URL of the page which shows the CAPTCHA.
  In this case, the user must verify that the URL in the CAPTCHA is the same of
  that shown in the browsers address bar.

- Assuming that the CAPTCHA is shown on a page accessible only using the
  https protocol, it signs the CAPTCHA using the Key Pair coming with the certificate used
  for the https connection. A Firefox plugin automatically verifies the signature.


Directory Structure
===================

scaptcha
    docs                        - Contains the documentation on how to use the library
    libs                        - Contains all the necessary third-party libraries.
    license                     - Contains license information.
    scaptcha-aeoforge           - The module which provides the integration with aeoforge.
    scaptcha-client             - The module which provides the Firefox Plugin.
    scaptcha-demo               - The module which provides a demo web-app.
    scaptcha-server             - The module which provides the server side part (servlets, SecureCAPTCHA,...)
    scaptcha.xml                - Ant build file

The sources are organized in the following way (per module):

src
    main                        - Contains the core sources
        java                    - Contains the core java sources
        resources               - Contains the core resources (configuration files and so on...)
    test
        java                    - Contains the test code for java sources.
        resources               - Contains the test code resources.
web                             - Contains the web sources.


Usage and Installation
======================

The project is based on the Ant build system. You can download it at http://ant.apache.org/
All necessary libraries are available in the libs directory.


Building instructions
=====================

Before building check the file scaptcha.properties and verify that the right jdk is used.

To build the project simply call from the root directory (scaptcha):

    ant -f scaptcha.xml

After a successful execution two files will be created into the root directory:
- SecureCAPTCHA.xpi: it is the Firefox plugin archive file to be installed in Firefox.
- scaptcha-aeoforge-1.0.0.jar: a single jar file containing the library classes.



AEOFORGE
========

To execute the server you have to generate a server certificate.
You can do that using the following command:

$JAVA_HOME/bin/keytool -genkey -alias scaptcha -keyalg RSA

enter the password "changeit" when requested.

Now you can launch the server in this way:

java -jar scaptcha-aeoforge-1.0.0.jar out/artifacts/scaptcha_aeoforge/ /Users/Angelo/.keystore changeit

where
- out/artifacts/scaptcha_aeoforge/ is the folder containing the web-app (it is created during the build phase)
- /Users/<user-name>/.keystore is the keysotre created by the keytool program.

After you have installed the Firefox plugin point the browser to the following url

https://localhost:8443/aeoforge/index.jsp

Verify that the url you see in the CAPTCHA is the same you see in the browser address bar.
Also, in the right-bottom position you should see a green icon which states that the Firefox plugin
has verified successful the Secure CAPTCHA.