%META:TOPICINFO{author="KoenMartens" date="1136326024" format="1.0" version="1.5"}%
---+!! <nop>%TOPIC%

Plugin for visual confirmation of new user registration, to prevent automated scripts to create users and spam your wiki with their url's to get a better google ranking. 

%TOC%

------

---++ Syntax Rules

	* None

---++ Examples

	* N/A

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>INTERWIKIPLUGIN_SHORTDESCRIPTION%==

	* One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
		* Set SHORTDESCRIPTION = Plugin for visual confirmation of new user registration.

	* Debug plugin: (See output in =data/debug.txt=)
		* Set DEBUG = 1

	* Custom settings (defaults shown):
		* Characters to use in generated strings:
			* Set CHARACTERS = ABCDEFGHKLMNPRSTVWXYZabcdeghpqsuvwxy@
		* Truetype font to use:
			* Set FONT = luxisbi.ttf
		* Number of random lines to add (use ==none== for 0):
			* Set LINES = 10
		* Number of random circles to add (use ==none== for 0):
			* Set CIRCLES = 10
		* Noise, percentage of pixels to flip randomly after generating graphics (use ==none== for 0%):
			* Set NOISE = 15

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
	  | *File:* | *Description:* |
	  | ==data/TWiki/VisualConfirmPlugin.txt== | Plugin topic |
	  | ==data/TWiki/VisualConfirmPlugin.txt,v== | Plugin topic repository |
	  | ==register.patch== | Patch for the register binary |
	  | ==templates/oopsregvisualconfirm.tmpl== | Error template |
	  | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
	* Apply the patch ==register.patch== to ==bin/register== (alternatively, patch register manual, see section below):
		* cd bin
		* patch < ../register.patch
	* Create the directories ==visualconfirm== and ==visualconfirm/db== in your ==pub/== directory, and make sure it is readable and writable by the user that TWiki is executing as.
		* mkdir -p pub/visualconfirm/db
		* chown -R nobody pub/visualconfirm
		* chmod -R 644 pub/visualconfirm
	* Restrict access to the database files, for example, by including the following in your httpd.conf:
<pre>
			&lt;Directory "/path/to/twiki/pub/visualconfirm/db"&gt;
			  deny from all
			&lt;/Directory&gt;
</pre>
	* Make sure the plugin has access to the preferred truetype font, by putting the ==.ttf== file in ==pub/visualconfirm/==
	* Test if the installation was successful:
		* Create a topic containing ==&lt;IMG SRC="%<nop>VISUALCONFIRMURL%"&gt;== and ==%<nop>VISUALCONFIRMHASH%==
		* When loading this topic you should see an obfuscated character string loaded as a png and a hexadecimal hash.
		* Check whether the hash database is properly protected by going to the url http://my.twiki.server/my/twiki/path/pub/visualconfirm/db/hashes.pag, you should see a permission denied message.
	* Now edit your TWiki.TWikiRegistration topic
		* Display the image !%VISUALCONFIRMURL% somewhere in your form, along with a text instructing new users to copy the obfuscated text into the appropriate text input.
		* Add the appropriate text input as ==Twk1VisualConfirm==
		* Add a hidden input as ==Twk1VisualConfirmHash==
		* For example, add this to your TWiki.TWikiRegistration:
<pre>
				&lt;tr&gt;
				  &lt;td valign="top" align="right"&gt;&lt;IMG SRC="%<nop>VISUALCONFIRMURL%"&gt;: &lt;br /&gt; (..) &nbsp; &lt/td&gt;
				  &lt;td&gt;&lt;input type="hidden" name="Twk1VisualConfirmHash" value="%<nop>VISUALCONFIRMHASH%"&gt;
						&lt;input type="text" name="Twk1VisualConfirm" size="5"&gt;&lt;/td&gt;
				&lt;/tr&gt;
</pre>
	* That's it.

---+++ Manually patching the register binary

Find the line in ==bin/register== that says:
<pre>
	 # everything OK
</pre>

Insert the code below directly *BEFORE* that line:

<pre>
	 # check valid visual confirmation
	 for( $x = 0; $x < $formLen; $x++ ) {
		$vcHash=$formDataValue[$x]
		  unless(not($formDataName[$x] eq "Visual Confirm Hash"));
		$vcTxt=$formDataValue[$x]
		  unless(not($formDataName[$x] eq "Visual Confirm"));
	 }

	 open(LOCKFILE,">".&TWiki::getPubDir()."/visualconfirm/db/hashes.lock");
	 flock(LOCKFILE,2);

	 dbmopen(%database, &TWiki::getPubDir()."/visualconfirm/db/hashes" ,0644);

	 if(!defined($database{$vcHash})) {
		$url = &TWiki::getOopsUrl( $webName, $topic, "oopsregvisualconfirm",
		  "The visual confirmation has expired.");
		TWiki::redirect( $query, $url );
		return;
	 }

	 my ($time,$txt)=split(',',$database{$vcHash});

	 if(not(lc($txt) eq lc($vcTxt))) {
		$url = &TWiki::getOopsUrl( $webName, $topic, "oopsregvisualconfirm",
		  "The character string you entered for visual confirmation is incorrect.");
		TWiki::redirect( $query, $url );
		return;
	 }
	 dbmclose(%database);

	 close(LOCKFILE);
</pre>

---++ Further Development

	* Make number of characters configurable
	* Make font size configurable
	* Find out how to safely delete images from the register binary

---++ Plugin Info

|  Plugin Author: | TWiki:Main.KoenMartens |
|  Plugin Version: | 03 Jan 2006 (V1.001) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  07 Oct 2005: | Initial version |
|  10 Oct 2005: | Strip hash and text from arguments to register binary, or they will end up in the newly created user topic. |
|  03 Jan 2006: | Fixed some problems with expiry, also optimised according to TWiki:TWiki.TWikiPlugins#FastPluginHints. |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | GD, Digest::MD5 |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle 98%, %TWIKIWEB%.FormattedSearch 98%, TWiki.TWikiRegistration (patched) 85% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins


-- TWiki:Main.KoenMartens - 07 Oct 2005

