Captcha Codes

A "captcha" code (an acronym for "Completely Automated Public Turing test to tell Computers and Humans Apart") is a mechanism that helps to ensure that it is a human that is accessing your web gadget instead of an automated system of some sort. This greatly enhances security and reduces the likelihood of abuse. For example, using a captcha code on a guestbook form can help to eliminate "spam" from automated scripts.

Captcha tests come in many forms, but the most common is a small graphic image that contains a randomly generated code word or number. A human can easily read and enter the code as part of the form submission, while a computer program cannot. If the code entered does not match the one displayed then the form submission is rejected. Typically the code in the graphic is made harder for a computer to "read" by using random colors, fonts, backgrounds, etc.

Each web gadget will have its own way of specifying that a captcha code should be used, but the configuration of the captcha code itself is the same across all web gadgets. The configuration file for a web gadget that uses a captcha code will contain a section that looks like this:

$CONFIG['CaptchaCodeLength'] = 4; $CONFIG['CaptchaBackgroundColor'] = "FFFFFF"; $CONFIG['CaptchaForegroundColor'] = "random"; $CONFIG['CaptchaCodeCharacters'] = "abcdefhjkmnprstuwxzACDEFGHJKMNPQRSTUWX34567"; $CONFIG['CaptchaFontList'] = "arial,verdana";

As with all configuration options, the captcha settings are specified as part of the $CONFIG[] array of values. All of the captcha settings are optional and have default values.

CaptchaCodeLength

This is the length of the captcha code to generate. The longer the code is, the more secure it will be against automated guessing, but the more cumbersome it will be for humans to enter. This value must be between 2 and 10. The default length is 4.

CaptchaBackgroundColor

This is the color to use for the background of the captcha code graphic. It should be expressed as an HTML hex color code that is exactly six characters long, or the word 'random'. The default value is 'random' which picks a random color.

CaptchaForegroundColor

This is the color to use for the text of the captcha code. It should be expressed as an HTML hex color code that is exactly six characters long, or the word 'random'. The default value is 'random' which picks a random color.

CaptchaCodeCharacters

This is a list of the characters that can be used to generate the captcha code. The more letters, numbers, and punctuation marks you specify in this list, the more secure it will be. However, watch out for characters that look similar (like the number 'one' and the letter 'el') as this could frustrate visitors. The default is to use most letters and some numbers but no punctuation marks.

CaptchaFontList

This is unset by default. Without this value the characters in the displayed captcha code will use a small set of internal fonts which are fairly similar in look. This setting allows you to specify a list of one or more TrueType fonts (that you supply) to use instead. The fonts must be copied into the same location as the web gadget and must have file names that end with '.ttf'. This setting makes for better looking captcha graphics as well as enhanced security (assuming you pick fonts that are harder for a computer program to "read").

$CONFIG['MySQLHostname'] = "sql3.islandnet.com"; $CONFIG['MySQLUsername'] = "myusername"; $CONFIG['MySQLPassword'] = "mypassword"; $CONFIG['MySQLDatabase'] = "mydatabase";

These settings specify the hostname, username, password, and database to use for tracking captcha codes (the exact values will be different than shown above of course). These are not captcha-specific settings as each web gadget may use the same database for other purposes as well. You do not need to create any tables in the database, the web gadget will create tables as necessary. You can use an existing MySQL database if you want, but we suggest creating a new one for all your web gadgets to share. You can create MySQL databases in our helpdesk under the "Databases" tab of the "My Account" page.

Audio Captcha Codes

If you want an audio version of the code, you first need an audio file for each possible letter or number that can appear in your captcha codes. These must be WAV files, and they must all be the same in terms of bitrate and sample size and should be mono. If you need a nice set of audio files, you can download these ones. You will need to place these sound files somewhere in your account where the gadget you're using can access them.

Once you have the audio files you want, you'll need to add some new settings to your config file:

CaptchaAudioFiles

This specifies the location of the individual audio files. This value must contain a '%s' placeholder, which will be replaced with a lowercase letter or number from the captcha code automatically. For example, is you placed all your audio files in an "audio" folder, you could use this setting:

$CONFIG['CaptchaAudioFiles'] = "audio/%s.wav";

CaptchaAudioVolume

This is the volume of the generated audio file as a percentage of the original audio files' volume. If you set this value to 100 then the volume will be the same as the original audio files. If this is set to 200, the volume will be doubled. If this is set to 50, it will be halved.

CaptchaAudioBackground

This value is optional. It lists one or more WAV files that will be played in the background. It's the audio equivalent of adding patterns to the the background of the visual captcha code. it makes it harder for a computer program to "listen" to the code. If more than one sound file is listed, one of them will be selected at random. If the file is shorter than the resulting audio file, it will be looped automatically. This must be the same format as the letter and number audio files (ie: WAV file, same bitrate, same sample size)

CaptchaAudioBackgroundVolume

This is the volume of the background audio file as a percentage of the original audio file's volume. If you set this value to 100 then the volume will be the same as the original audio files. If this is set to 200, the volume will be doubled. If this is set to 50, it will be halved. Normally you would want the background audio file to be a little quieter than the letters and numbers.

CaptchaAudioStartDelay

This value adds some silence to the beginning of the generated audio file (before it combined with any background sound). It is a floating point number. For example, a value of 1.0 would add 1 second, 2.5 would add 2.5 econds, etc.

CaptchaAudioDelayend

This value adds some silence in between each letter/number of the generated audio code (before it combined with any background sound). It is a floating point number. For example, a value of 1.0 would add 1 second, 2.5 would add 2.5 econds, etc.

CaptchaAudioEndDelayend

This value adds some silence to the end of the generated audio file (before it combined with any background sound). It is a floating point number. For example, a value of 1.0 would add 1 second, 2.5 would add 2.5 econds, etc.

CacheDirectoryend

In order for this to work, the generated audio file must be saved to disk. This settings specified a directory where the file will be cached. This directory must exist and be writable by the gadget.

Using Captcha Codes

To generate and display a captcha code you simply need to embed an IMG tag that calls the web gadget in captcha mode. For example, if the gadget in question happens to be "inmail.php", then you might embed an image in your form with this code:

<img src="inmail.php?captcha">

The web gadget sees the 'captcha' parameter and knows to generate a new captcha code and output it as an image. Sometimes the generated image is hard to read, so it's always a good idea to provide the user with a way of generating a new one. This is easily done by adding a little bit of Javascript code to the IMG tag like this:

<img src="inmail.php?captcha" onclick="this.src='inmail.php?captcha'+(new Date()).getTime();">

Now whenever the image is clicked, the image src is changed, which causes a new code to be generated and a new image to be displayed. The current date and time are added to the end to ensure that the image src changes each time, otherwise the browser would simply use the last cached image.

One of the main problems with captcha codes is that they are often incompatible with folks who are visually impaired. For this reason our captcha code system also supports speech. That is, you can optionally add a button beside the captcha code that will speak the code out loud when the user clicks on it. To add a speech button you would add something like this to your form:

<span id="speech"></span>
<img src="listen.gif" onclick="document.getElementById('speech').innerHTML=
   '<embed src=inmail.php?speak'+(new Date()).getTime() +'.wav 
   hidden=true autostart=true loop=false width=0 height=0>'"
   alt="" title="Click to hear the code spoken">

The second line is wrapped for readability. Here's what it does: it adds an empty HTML span named "speech", followed by an image (named "listen.gif" in this example, but you will need to supply your own image).

When the image is clicked, the contents of the empty span are rewritten to include an embedded sound file (which is actually a link back to the web gadget itself with the "speak" parameter). The settings on the embedded sound file cause it to play automatically once it loads.

Like the example for the image, we add the current date and time to prevent the browser from simply playing the old cached audio file. We also add ".wav" to this value for those browsers that depend on the file extension for determining how to play audio.

To see both the image and audio captcha support in action, check out the inMail Demo.