.. You may want to use the usual include line. Uncomment and adjust the path. 
.. include:: ../Includes.txt


===============
EXT: Spamshield
===============

:Created:
      2010-02-18T17:33:18

:Changed by:
      Hauke Preuß

:Changed:
      2011-08-07T11:23:00.560000000

:Classification:
      spamshield

:Keywords:
      forEditors, forAdmins, forIntermediates

:Author:
      Hauke Hain

:Email:
      hhpreuss@googlemail.com

:Info 4:


:Language:
      en


|img-1| |img-2| EXT: Spamshield - spamshield


.. _EXT-Spamshield:

EXT: Spamshield
===============

Extension Key: spamshield

Language: en

Keywords: forEditors, forAdmins, forIntermediates

Copyright 2005-2011, Hauke Hain, <hhpreuss@googlemail.com>, Ronald
Steiner <Ronald.Steiner [at] googlemail [dot] com>, Alexander Kellner
<AlexanderKellner [at] einpraegsam [dot] net>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

\- a GNU/GPL CMS/Framework available from www.typo3.org

.. _Table-of-Contents:

Table of Contents
-----------------

`EXT: Readable name of your extension 1
<#1.EXT:%20Readable%20name%20of%20your%20extension|outline>`_

**`Introduction 3 <#1.1.Introduction|outline>`_**

`What does it do? 3 <#1.1.1.What%20does%20it%20do_|outline>`_

`Screenshots 3 <#1.1.2.Screenshots|outline>`_

**`Users manual 4 <#1.2.Users%20manual|outline>`_**

`FAQ 4 <#1.2.1.FAQ|outline>`_

**`Administration 5 <#1.3.Administration|outline>`_**

`FAQ 5 <#1.3.1.FAQ|outline>`_

**`Configuration 6 <#1.4.Configuration|outline>`_**

`FAQ 6 <#1.4.1.FAQ|outline>`_

`Reference 6 <#1.4.2.Reference|outline>`_

**`Tutorial 7 <#1.5.Tutorial|outline>`_**

**`Known problems 8 <#1.6.Known%20problems|outline>`_**

**`To-Do list 9 <#1.7.To-Do%20list|outline>`_**

**`ChangeLog 10 <#1.8.ChangeLog|outline>`_**

`Important guidelines 11 <#2.Important%20guidelines|outline>`_

**`Issues with Open Office documentation for TYPO3 12 <#2.1.Issues%20w
ith%20Open%20Office%20documentation%20for%20TYPO3|outline>`_**

`Inserting images 12 <#2.1.1.Inserting%20images|outline>`_

`Paragraph styles 12 <#2.1.2.Paragraph%20styles|outline>`_

`Linking 13 <#2.1.3.Linking|outline>`_

`Meta data and updates 13
<#2.1.4.Meta%20data%20and%20updates|outline>`_

`HowTo: Update a manual to the new layout 13 <#2.1.5.HowTo:%20Update%2
0a%20manual%20to%20the%20new%20layout|outline>`_

`HowTo: (alternative) Import the styles from another document 14 <#2.1
.7.HowTo:%20(alternative)%20Import%20the%20styles%20from%20another%20d
ocument|outline>`_

`HowTo: Fix the Table Of Contents when it is empty 14 <#2.1.8.HowTo:%2
0Fix%20the%20Table%20Of%20Contents%20when%20it%20is%20empty%20|outline
>`_

`HowTo: Fix the Table Of Contents when a chapter is missing 14 <#2.1.9
.HowTo:%20Fix%20the%20Table%20Of%20Contents%20when%20a%20chapter%20is%
20missing%20|outline>`_

`Help by documentation.openoffice.org 14
<#2.1.10.Help%20by%20documentation.openoffice.org|outline>`_


.. _Introduction:

Introduction
------------


.. _What-does-it-do:

What does it do?
^^^^^^^^^^^^^^^^

- Universal invisible Spamshield for TYPO3: check for referer,
  useragent, javascript, httpbl.org-blacklist, and honeypot-fields. You
  can specify which checks should be performed, which spam weight each
  check has and the exactly value of the total spam weight that must be
  reached in order to block the client.

- Spamshield logs Spam. It can is disabled by default. On top of that a
  scheduler task ist provided to delete old log entries so the database
  does not run out of space.

- The installation is very easy. The default configuration will serve
  for most needs. Lots of configuration options help to adjust to
  special requirements.


.. _Spamcheck:

Spamcheck
"""""""""


.. _First-line:

First line
~~~~~~~~~~

The first line of defense blocks always. No form must be submitted.

**httpbl.org – balcklist check:** httpbl.org provides a huge IP-List.
IP's belonging to spam-robots, harvester are on a “balcklist”. Please
get an access key from httpbl.org to use this check. - a very
effective check!


.. _Second-line:

Second line
~~~~~~~~~~~

The second line of defense blocks only if a form has been submitted.

- **User Agent:** Every browser sends a HTTP\_USER\_AGENT value to a
  server. A missing HTTP\_USER\_AGENT value almost always indicates a
  spammer bot.

- **Referrer:** Most browsers and all modern browsers (FF, IE, Opera, …)
  send a HTTP\_REFERER value. In the case of data submission form a form
  it should contain the url of the page containing the form. If data is
  send from a foreign source to your web page the HTTP\_REFERER does
  show a different url or is not send at all. So a missing or wrong
  HTTP\_REFERER could mean a spam bot is submitting data.Notice: There
  are several firewall and “security” products which block HTTP\_REFERER
  by default on normal web browsers. Therefore Spamshield uses the check
  for the HTTP\_REFERER only as one of more checks.

- **JavaScript and Cookie check:** With Spamshield each page of your web
  page sends a small cookie per JavaScript to the web browser. Most
  modern browsers accept cookies and support JavaScript. As a data
  submission can only be done when the page with the form has been
  visited before normal users have the cookie. Spam bots in most cases
  can neither interpret JavaScript nor accept Cookies. So they don't
  carry the cookie. This is a very simple and effective check.

- **Honey pot check:** Spamshields includes fields to any form on your
  web page that are not visible for the user by CSS or other techniques.
  All modern web browsers interpret CSS very well. So normal users won't
  see those fields while spam bots won't notice a difference to normal
  form fields. Therefore if this fields are filled it was almost
  certainly a spam bot. A very effective and secure check.


.. _Blocked-users:

Blocked users
"""""""""""""

If spam is detected a message will be shown. There is no redirection
so spam bots won't notice that something is wrong. You can force
spamshield to redirect to any TYPO3 page. If the frontend plugin of
spamshield is on this page the user can solve a captcha. If the
captcha is correct solved the user get redirected to the page he comes
from and the form gets submittes as if everything went normal.


.. _Screenshots:

Screenshots
^^^^^^^^^^^

Feel free to send us screenshots that might be helpful here. Thanks.


.. _Users-manual:

Users manual
------------

- Import SpamShield from Extension repository and install it.

- You can configure rulesets, redirection, logging, blocking message and
  many more. Have a look at the configuration part of the documentation
  for details.

- Add the static template to your main template of the site.

- You can configure the honeypots with TypoScript. Have a look at the
  configuration part of the documentation for details.


.. _Administration:

Administration
--------------

Afer you have installed the extension as in user manual described you
can configure spamshield to your needs. Have a look at the
configuration chapter of this manual. In this chapter we show some
special features of spamshield.

- **Frontent plugin with captcha if spam detected** You may insert the
  spamshield frontend plugin to any TYPO3 page. Enter this pid in the
  configuration of spamshield in the extension manager to the property
  “redirecttopid”. After saving this value blocked users gets redirected
  now instead of just getting the blocking message. The frontent plugin
  delivers a captcha and a submit button. If the captcha is solved the
  user gets redirected to the page he comes from and the post variables
  are getting submitted too. As a result it will lead the user in most
  cases to the expected result.NOTE: You have to install either the
  “sr\_freecap” or “captcha” extension. Hint: if you have installed both
  extensions, “sr\_freecap” will be used.

- **Add new honepot field** Just enter new fields to the
  *plugin.tx\_spamshield.add2forms.fields* section of the spamshield
  TypoScript. Spamshield recognises the fields by their name. So you
  have to the “honeypot” property (Honepot field names) of the extension
  configuration in the extension manager, separated by comma.NOTE:
  Spamshield needs the following hidden input field in order to work. Do
  not remove it!
  
  ::
  
     <input type="hidden" name="spamshield[mark]" value="true" />

- **Disable check for specific forms** Just enter a valid regular
  expression to your TypoScript setting to have spamshield ignore forms
  that matches any expression in:  *plugin.tx\_spamshield.add2forms.off*

- **Disable spamshield for a whole pageExample**
  
  Here spamshield gets disabled for logged in users:

::

      [loginUser = *]
          page.headerData.5289 >
      plugin.tx_spamshield >
    [global] 


.. _Configuration:

Configuration
-------------


.. _TypoScript-Reference:

TypoScript Reference
^^^^^^^^^^^^^^^^^^^^

.. ### BEGIN~OF~TABLE ###


.. _add2forms:

add2forms
"""""""""

.. container:: table-row

   Property
         add2forms
   
   Data type
         boolean
   
   Description
         Enables or disables first level of defense.
   
   Default
         1



.. _add2forms-off:

add2forms.off
"""""""""""""

.. container:: table-row

   Property
         add2forms.off
   
   Data type
         CAO
   
   Description
         Regular expression for a form to disable the add2forms option.
         **Important:** The default value must remain in order to have the
         frontend plugin work correctly. It prevents the form of the plugin be
         adjusted by add2forms twice. If the setting is missing it does not
         matter if the Captcha is solved correctly, spamshield will think that
         there is no spam.
   
   Default
         5 = /name=\'frmnoadd2form\'/



.. _add2forms-position:

add2forms.position
""""""""""""""""""

.. container:: table-row

   Property
         add2forms.position
   
   Data type
         string
   
   Description
         The position of the honeypots.Valid options: start, end, start-end,
         rnd
   
   Default
         start-end



.. _add2forms-fields:

add2forms.fields
""""""""""""""""

.. container:: table-row

   Property
         add2forms.fields
   
   Data type
         CAO
   
   Description
         Define your own honepot fields. Please note: Spamshield detects a
         honepot by its name. So you must make spamshield familiar with the
         names. So you have to the “honeypot” property (Honepot field names) of
         the extension configuration in the extension manager, separated by
         comma.Important: The secured form must not have a input field with the
         same name!
         
         **Example:**
         
         ::
         
            fields {
            10 = <input type="text" name="email" value="" style="display:none !important;" />
            20 = <input type="text" name="name" value="" class="tx_spamshield_honey1" />
            30 = <input type="text" name="first-name" value="" style="position: absolute !important; margin: 0 0 0 -9999px !important;" />
            40 = <input type="text" name="e-mail" value="" class="tx_spamshield_honey1" />
            50 = <input type="hidden" name="spamshield[mark]" value="true" />
            }
   
   Default
         See example


.. ###### END~OF~TABLE ######

[tsref:plugin.tx\_spamshield]


.. _Extension-manager-Reference:

Extension manager Reference
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. ### BEGIN~OF~TABLE ###


.. _firstLine:

firstLine
"""""""""

.. container:: table-row

   Property
         firstLine
   
   Data type
         string
   
   Description
         Ruleset for first line spamshield: Will be blocked ALWAYS!Enter the
         rule name and the spam weight separated by a comma. Separated rules by
         semicolon.
   
   Default
         httpbl,1



.. _secondLine:

secondLine
""""""""""

.. container:: table-row

   Property
         secondLine
   
   Data type
         string
   
   Description
         Ruleset for second line spamshield: Will be blocked on form
         submission!Enter the rule name and the spam weight separated by a
         comma. Separated rules by semicolon.
   
   Default
         useragent,1;referer,1;cookie,1;honeypot,1



.. _honeypot:

honeypot
""""""""

.. container:: table-row

   Property
         honeypot
   
   Data type
         string
   
   Description
         Honepot field names: Comma separated names of the input fields defined
         in the  *plugin.tx\_spamshield.add2forms.fields* TypoScript setting.
         Spamshield recognises the honepots by the names entered
         here.Important: The honepot name has to be unique on the page!
   
   Default
         email,e-mail,name,first-name



.. _weight:

weight
""""""

.. container:: table-row

   Property
         weight
   
   Data type
         integer
   
   Description
         Crictical Weight for spam: A user is blocked when this spam weight is
         at least reached.
   
   Default
         2



.. _accesskey:

accesskey
"""""""""

.. container:: table-row

   Property
         accesskey
   
   Data type
         string
   
   Description
         httpbl.org Access Key for httpbl check. Get one from httpbl.org
   
   Default



.. _type:

type
""""

.. container:: table-row

   Property
         type
   
   Data type
         int
   
   Description
         httpbl - Blocking type for httpbl check.
   
   Default
         2



.. _whitelist:

whitelist
"""""""""

.. container:: table-row

   Property
         whitelist
   
   Data type
         string
   
   Description
         Referer whitelist: If you want to recieve form data from exteranal
         pages, you can define them in the white list (comma separated).
   
   Default



.. _logpid:

logpid
""""""

.. container:: table-row

   Property
         logpid
   
   Data type
         integer
   
   Description
         The PID where you want spam to be logged. Zero = no logging.Must be
         enabled if you use the fronten plugin.
   
   Default
         0



.. _redirecttopid:

redirecttopid
"""""""""""""

.. container:: table-row

   Property
         redirecttopid
   
   Data type
         integer
   
   Description
         The PID where you want the user to be redirected after spam has been
         detected. Zero = no redirection.Must be enabled if you use the fronten
         plugin.
   
   Default
         0



.. _message:

message
"""""""

.. container:: table-row

   Property
         message
   
   Data type
         string
   
   Description
         The message that is send to blocked users. (If not “redirecttopid” is
         used.)
         
         **Example:**
         
         ::
         
            <h1>You have been blocked.</h1><p>Sorry for that.</p>
   
   Default
         See example


.. ###### END~OF~TABLE ######


.. _Known-problems:

Known problems
--------------

- **JavaScript and Cookie-Check and multiple Domains** Problem:If you
  are using forms that POST data across multiple domains / subdomains.
  Spamshield does not find the cookies. Therefore JavaScript and Cookie
  check will always fail.
  
  Solution:
  
  Go to the TYPO3 install-tool and define “cookieDomain”

- **Referer-Check and multiple Domains**

- Problem:If you are using forms that POST data across multiple domains
  / subdomains. Spamshield Referer check will block this as spam.
  
  Solution:
  
  Define all your domains the config of the install tool:

::

      whitelist = domain1.de, domain2.com

Feel free to submit bugs at: `TYPO3 Forge
<http://forge.typo3.org/projects/extension-rs_spamshield/>`_


.. _To-Do-list:

To-Do list
----------

- Captcha templates should be configurable by TypoScript.

- Feeld free to submit feature request or other suggestions at out
  project page: `TYPO3 Forge <http://forge.typo3.org/projects/extension-
  rs_spamshield/>`_


.. _ChangeLog:

ChangeLog
---------

.. ### BEGIN~OF~TABLE ###


.. _1-0-0:

1.0.0
^^^^^

.. container:: table-row

   Version
         1.0.0
   
   Changes
         - New frontent plugin with captcha check to give intranet users a chance
           to submit forms
         
         - Optional redirection to any TYPO3 page if user gets blocked
         
         - Scheduler taskt to delete spam logs
         
         - honepot fields could be added without having to change the hardcoded
           source code (new config)



.. _0-0-26:

0.0.26
^^^^^^

.. container:: table-row

   Version
         0.0.26
   
   Changes
         - Complete rewrite
         
         - Make it more easy to install and configure
         
         - Remove some options to get it simple and fast
         
         - Add httpbl.org balcklist check
         
         - Bugfixes
         
         - Use a different hook for analyzing the forms to get spam more early


.. ###### END~OF~TABLE ######

|img-2| 9


.. ######CUTTER_MARK_IMAGES######

.. |img-1| image:: img-1.png
.. :align: left

.. |img-2| image:: img-2.png
.. :border: 0
.. :height: 21
.. :hspace: 9
.. :id: Grafik2
.. :name: Grafik2
.. :width: 87