BotDetect ASP.NET 1.1 CAPTCHA Randomization C# Code Sample (BotDetect v2.0; deprecated)

documentation > asp.net 1.1 captcha > samples

Please Note

The information on this page is out of date and applies to a deprecated version of BotDetect™ CAPTCHA (v2.0).

An up-to-date equivalent page for the latest BotDetect Captcha release (v3) is BotDetect v3 ASP.NET CAPTCHA Randomization code sample.

General information about the major improvements in the current BotDetect release can be found at the What's New in BotDetect v3.0 page.

The BotDetect ASP.NET CAPTCHA randomization sample shows how you can easily randomize various Captcha control parameters, which can significantly improve the CAPTCHA protection security and is the best way to take full advantage of the 50 different CAPTCHA algorithms shipped with BotDetect.

Sample Project Location
Default.aspx
Default.aspx.cs
RandomizationHelper.cs
Web.config

Sample Project Location

By default, this sample project is installed at
C:\Program Files\Lanapsoft\BotDetect\ASP.NET 1.1\v2.0\Samples\CSharpBotDetect2RandomDemo\.

You can also run it from the Start Menu:
Programs > Lanapsoft > BotDetect > ASP.NET 1.1 > v2.0 > Samples > C# BotDetect CAPTCHA Randomization Sample.

[back to top]

Default.aspx

Full Source Code Listing

<%@ Page language="c#" Codebehind="Default.aspx.cs" 
  AutoEventWireup="false" Inherits="CSharpBotDetectDemo._Default" %>

<%@ Register Assembly="Lanap.BotDetect" Namespace="Lanap.BotDetect" 
  TagPrefix="BotDetect" %>

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
    <title>BotDetect Random Demo</title>
    <link type='text/css' rel='Stylesheet' href="StyleSheet.css" />
</head>
<body>
    <form id="form1" runat="server">
    <fieldset id="Preview">
        <legend>
            <span id="PreviewLegend">CAPTCHA Preview</span>
        </legend>
        <div id="PromptDiv">
            <span id="Prompt">Type the characters you see in 
              the picture</span>
        </div>
        <div id="CaptchaDiv">
            <BotDetect:Captcha ID="SampleCaptcha" runat="server" />
        </div>
        <div id="ValidationDiv">
            <asp:TextBox ID="CodeTextBox" runat="server">
            </asp:TextBox>
            <asp:Button ID="ValidateButton" runat="server" />
            <asp:Label ID="MessageCorrectLabel" runat="server">
            </asp:Label>
            <asp:Label ID="MessageIncorrectLabel" runat="server">
            </asp:Label>
        </div>
    </fieldset>
    <div id="Note">
        <span>NOTE: the Trial version will use "LANAP" instead of a 
          random code in 50% of renderings.</span>
    </div>
    </form>
</body>
</html>

Explanation

Lines required to add the BotDetect CAPTCHA control to the ASP.NET form are bold. To use the <BotDetect:Captcha> control, we must first register the Lanap.BotDetect.dll assembly using the <%@Register %> directive.

The form also contains an <asp:TextBox> for the user input, an <asp:Button> to submit the page, and a pair of <asp:Label> controls which are used to show the CAPTCHA validation result. The rest of the file is either generated by Visual Studio 2005 by default, or just defines the layout and visual presentation of the page.

There is no difference between the .aspx file of this sample and the basic one, since all CAPTCHA randomization is performed in codebehind.

[back to top]

Default.aspx.cs

Full Source Code Listing

using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Web;
using System.Web.SessionState;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.HtmlControls;

namespace CSharpBotDetectDemo
{
    /// <summary>
    /// Summary description for _Default.
    /// </summary>
    public class _Default : System.Web.UI.Page
    {
        protected Lanap.BotDetect.Captcha 
            SampleCaptcha;
						
        protected System.Web.UI.WebControls.Button 
            ValidateButton;
						
        protected System.Web.UI.WebControls.TextBox 
            CodeTextBox;
						
        protected System.Web.UI.WebControls.Label 
            MessageIncorrectLabel;
						
        protected System.Web.UI.WebControls.Label 
            MessageCorrectLabel;

        #region Web Form Designer generated code
        override protected void OnInit(EventArgs e)
        {
            //
            // CODEGEN: This call is required by the ASP.NET 
            // Web Form Designer.
            //
            InitializeComponent();
            base.OnInit(e);
        }

        /// <summary>
        /// Required method for Designer support - do not modify
        /// the contents of this method with the code editor.
        /// </summary>
        private void InitializeComponent()
        { 
            this.Init += new System.EventHandler(this.Page_Init);
						
            this.PreRender += 
                new System.EventHandler(this.Page_PreRender);
        }
        #endregion

        protected void Page_Init(object sender, EventArgs e)
        {
            /// register CAPTCHA-specific event handler
            SampleCaptcha.PreDrawCaptchaImage += 
                new PreDrawCaptchaImageHandler(
                this.SampleCaptcha_PreDrawCaptchaImage);
        }

        protected void Page_PreRender(object sender, EventArgs e)
        {
            /// initial page setup
            if (!IsPostBack)
            {
                /// set control text
                ValidateButton.Text = "Validate";
                MessageCorrectLabel.Text = "Correct!";
                MessageIncorrectLabel.Text = "Incorrect!";

                /// these messages are shown only after validation
                MessageCorrectLabel.Visible = false;
                MessageIncorrectLabel.Visible = false;
            }
						
            // clear user input on Reload button clicks
            string scriptTemplate = @"<script type='text/javascript'>
              function LBD_ClearUserInput() {{
                var LBD_textBox = document.getElementById('{0}');
                if(LBD_textBox) {{
                  LBD_textBox.value = '';
                }}
              }}
              LBD_RegisterHandler('PreReloadCaptchaImage', 
                LBD_ClearUserInput);
            </script>";
            ";
            string script = String.Format(scriptTemplate, 
              CodeTextBox.ClientID);
					
            if (!Page.IsClientScriptBlockRegistered(
                "CaptchaReloadClearInput"))
            {
              Page.RegisterClientScriptBlock("CaptchaReloadClearInput", 
                script);
            }

            // automatically lowercase user input
            CodeTextBox.Attributes.Add("onkeyup", 
                "this.value = this.value.toLowerCase();");

            if (IsPostBack)
            {
                /// validate the input code, and show the 
                /// appropriate message 
                string code = CodeTextBox.Text.Trim().ToUpper();
                if (SampleCaptcha.Validate(code))
                {
                    MessageCorrectLabel.Visible = true;
                    MessageIncorrectLabel.Visible = false;
                }
                else
                {
                    MessageCorrectLabel.Visible = false;
                    MessageIncorrectLabel.Visible = true;
                }

                /// clear previous user code input
                CodeTextBox.Text = null;
            }
        }
				
        /// <summary>
        /// all CAPTCHA randomization should be performed in this 
        /// event handler instead of Page_Load or Page_PreRender, 
        /// because this event is also fired for direct CAPTCHA 
        /// image requests (which skip the page events since the 
        /// page is never loaded), for example when clicking the 
        /// Reload CAPTCHA button repeatedly
        ///</summary>
        void SampleCaptcha_PreDrawCaptchaImage(object sender, 
            EventArgs e)
        {
            ICaptcha captcha = sender as ICaptcha;
            if (captcha.CaptchaId != SampleCaptcha.CaptchaId)
            {
              return;
            }

            /// randomize code generation properties
            captcha.CodeType = RandomizationHelper.GetRandomCodeType();
				
            captcha.CodeLength = 
                RandomizationHelper.GetRandomCodeLength(4, 6);

            /// randomize text style
            TextStyleEnum[] styles = { 
                TextStyleEnum.Lego, TextStyleEnum.MeltingHeat, 
                TextStyleEnum.Ghostly, TextStyleEnum.FingerPrints, 
                TextStyleEnum.Graffiti2, TextStyleEnum.Bullets2, 
                TextStyleEnum.CaughtInTheNet2, TextStyleEnum.Collage, 
                TextStyleEnum.Chalkboard
            };
        
            captcha.TextStyle = 
                RandomizationHelper.GetRandomTextStyle(styles);
        }
    }
}

Explanation

In the Page_Init phase of the ASP.NET page life-cycle, we register a special event handler to be executed before every CAPTCHA image is generated, in which we perform the CAPTCHA randomization. Since CAPTCHA images are generated and sent to the client in a Http request separate from the one loading the ASP.NET page (when this code gets executed), we add this event handler to ensure the CAPTCHA is randomized every time it is drawn, and not only once per page load.

This is important because the CAPTCHA image requests don't have to be tied to the number of page loads - most notably, when using the Reload CAPTCHA button, and when bots are accessing the CAPTCHA image directly, it's possible that many CAPTCHA images will be generated after only a single page load (and the related Page_PreRender execution).

In the Captcha_PreDrawCaptchaImage handler, the Captcha control instance is available as the sender parameter. To make the randomization as simple as possible, we use the RandomizationHelper class, which allows us to get a random value of a given parameter from all available values (as the CAPTCHA CodeType), or from a given range of values (as the CAPTCHA CodeLength), or from the given set of values (as the CAPTCHA TextStyle).

You can also randomize other CAPTCHA properties in a similar manner, but the CAPTCHA drawing algorithm and the CAPTCHA code length are the ones that improve the CAPTCHA security the most when randomized. Every individual CAPTCHA algorithm can be theoretically and eventually be broken (given enough effort), but if the bot also has to recognize the algorithm used for every image, the task becomes an order of magnitudes harder. Also, several popular CAPTCHA algorithms have been broken because they used a fixed number of characters in their images – "find 5 characters in this image" is inherently a much easier task to automate than "find an unknown number of characters in this image".

[back to top]

RandomizationHelper.cs

Full Source Code Listing

using System;
using System.Drawing;
using System.Collections;
using System.Collections.Specialized;
using System.Text;

using Lanap.BotDetect;

/// <summary>
/// Summary description for RandomizationHelper
/// </summary>
public sealed class RandomizationHelper
{
    private RandomizationHelper()
    {
        // constructor omitted, static methods only
    }

    /// a single global generator is used for all random numbers
    private static readonly Random _rand = new Random();

    public const CodeTypeEnum DefaultCodeType = 
        CodeTypeEnum.AlphaNumeric;

    public static CodeTypeEnum GetRandomCodeType(
        params CodeTypeEnum[] usedValues)
    {
        CodeTypeEnum codeType = DefaultCodeType;

        if (0 == usedValues.Length)
        {
            int max = Enum.GetValues(typeof(CodeTypeEnum)).Length;

            codeType = (CodeTypeEnum)(_rand.Next(max));
        }
        else if (1 == usedValues.Length)
        {
            codeType = usedValues[0];
        }
        else
        {
            int max = usedValues.Length;
            int index = _rand.Next(max);

            codeType = usedValues[index];
        }

        return codeType;
    }

    public const int DefaultCodeLength = 5;
    public const int MinCodeLength = 1;
    public const int MaxCodeLength = 15;

    public static int GetRandomCodeLength()
    {
        return GetRandomCodeLength(0, 0);
    }

    public static int GetRandomCodeLength(int max)
    {
        return GetRandomCodeLength(0, max);
    }

    public static int GetRandomCodeLength(int min, int max)
    {
        if ((max > MaxCodeLength) || (max < MinCodeLength))
        {
            max = MaxCodeLength;
        }

        if ((min < MinCodeLength) || (min > max))
        {
            min = MinCodeLength;
        }

        return _rand.Next(min, max + 1);
    }

    public static readonly ImageFormatEnum DefaultImageFormat = 
        ImageFormatEnum.Jpeg;

    public static ImageFormatEnum GetRandomImageFormat(
        params ImageFormatEnum[] usedValues)
    {
        ImageFormatEnum imageFormat = DefaultImageFormat;

        if (0 == usedValues.Length)
        {
            int max = Enum.GetValues(typeof(ImageFormatEnum)).Length;

            imageFormat = (ImageFormatEnum)(_rand.Next(max));
        }
        else if (1 == usedValues.Length)
        {
            imageFormat = usedValues[0];
        }
        else
        {
            int max = usedValues.Length;
            int index = _rand.Next(max);

            imageFormat = usedValues[index];
        }

        return imageFormat;
    }

    public static readonly Size DefaultImageSize = new Size(250, 50);
    public static readonly Size MinImageSize = new Size(50, 40);
    public static readonly Size MaxImageSize = new Size(500, 200);

    public static Size GetRandomImageSize()
    {
        return GetRandomImageSize(new Size(0, 0), new Size(0, 0));
    }

    public static Size GetRandomImageSize(Size maxSize)
    {
        return GetRandomImageSize(new Size(0, 0), maxSize);
    }

    public static Size GetRandomImageSize(Size minSize, Size maxSize)
    {
        /// determine width
        if ((maxSize.Width > MaxImageSize.Width) || 
            (maxSize.Width < MinImageSize.Width))
        {
            maxSize.Width = MaxImageSize.Width;
        }
        if ((minSize.Width < MinImageSize.Width) || 
            (minSize.Width > maxSize.Width))
        {
            minSize.Width = MinImageSize.Width;
        }
        int width = _rand.Next(minSize.Width, maxSize.Width + 1);

        /// determine height
        if ((maxSize.Height > MaxImageSize.Height) || 
            (maxSize.Height < MinImageSize.Height))
        {
            maxSize.Height = MaxImageSize.Height;
        }
        if ((minSize.Height < MinImageSize.Height) || 
            (minSize.Height > maxSize.Height))
        {
            minSize.Height = MinImageSize.Height;
        }
        int height = _rand.Next(minSize.Height, maxSize.Height + 1);

        /// the result
        return new Size(width, height);
    }

    public const TextStyleEnum DefaultTextStyle = 
        TextStyleEnum.Chalkboard;

    public static TextStyleEnum GetRandomTextStyle(
        params TextStyleEnum[] usedValues)
    {
        TextStyleEnum textStyle = DefaultTextStyle;

        if (0 == usedValues.Length)
        {
            int max = Enum.GetValues(typeof(TextStyleEnum)).Length;

            textStyle = (TextStyleEnum)(_rand.Next(max));
        }
        else if (1 == usedValues.Length)
        {
            textStyle = usedValues[0];
        }
        else
        {
            int max = usedValues.Length;
            int index = _rand.Next(max);

            textStyle = usedValues[index];
        }

        return textStyle;
    }
}

Explanation

RandomizationHelper is a small utility class which you can use in your projects to simplify various CAPTCHA parameter randomization.

For each CAPTCHA parameter which can take a numeric or enumerated value, this class provides a static method returning a random value. Each parameter has a default value, and numeric parameters also have predefined minimum and maximum values.

All randomization methods take a variable number of parameters, either via multiple method overloads or via the params keyword.

Methods returning numeric values (for example, CodeLength) behave in the following manner:

If no parameters are given, the random value is selected between the predefined minimum and maximum values.
If a single value is given as a parameter, the random value is selected between the predefined minimum and the given value as the maximum. Note that it is not possible to use a maximum greater than the predefined one, only a lesser one.
If two values are given as parameters, the random value is selected between the first value as the minimum and the second value as the maximum. Note that it is not possible to use a maximum greater than the predefined one, or a minimum lesser than the predefined one.

Methods returning enumerated values (for example, CodeType) behave in the following manner:

If no parameters are given, the random value is selected from all possible enumeration values.
If a single value is given as the parameter, it is returned as the result - be careful not to pass a single value to these methods, since there will be no randomization. And if you want to use a single value, just assign it to the appropriate parameter directly.
If a set (i.e. an array) of values is given as the parameter, the random value is selected from within that set.

Of course, you could also use such randomization code directly in your projects, but encapsulating it in the RandomizationHelper class is made available for convenience and better code readability.

[back to top]

Web.config

Full Source Code Listing

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    
  <system.web>
  
  <httpHandlers>
    <add verb="*" path="LanapCaptcha.aspx" 
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect"/>
  </httpHandlers>

  <!-- DYNAMIC DEBUG COMPILATION
    Set compilation debug="true" to enable ASPX debugging. Otherwise, 
    setting this value to false will improve runtime performance of 
    this application. Set compilation debug="true" to insert debugging 
    symbols (.pdb information) into the compiled page. Because this 
    creates a larger file that executes more slowly, you should set 
    this value to true only when debugging and to false at all other 
    times. For more information, refer to the documentation about 
    debugging ASP.NET files.
  -->
  <compilation 
    defaultLanguage="c#"
    debug="false"
  />

  <!-- CUSTOM ERROR MESSAGES
    Set customErrors mode="On" or "RemoteOnly" to enable custom error 
    messages, "Off" to disable. 
		
    Add <error> tags for each of the errors you want to handle.

    "On" Always display custom (friendly) messages.
		
    "Off" Always display detailed ASP.NET error information.
		
    "RemoteOnly" Display custom (friendly) messages only to users not 
      running on the local Web server. This setting is recommended for 
      security purposes, so that you do not display application detail 
      information to remote clients.
  -->
  <customErrors 
    mode="RemoteOnly" 
  /> 

  <!-- AUTHENTICATION 
    This section sets the authentication policies of the application. 
    Possible modes are "Windows", "Forms", "Passport" and "None".

    "None" No authentication is performed. 
		
    "Windows" IIS performs authentication (Basic, Digest, or 
    Integrated Windows) according to its settings for the 
    application. Anonymous access must be disabled in IIS. 
		
    "Forms" You provide a custom form (Web page) for users to 
    enter their credentials, and then you authenticate them 
    in your application. A user credential token is stored 
    in a cookie.
		
    "Passport" Authentication is performed via a centralized 
    authentication service provided by Microsoft that offers 
    a single logon and core profile services for member sites.
  -->
  <authentication mode="Windows" /> 

  <!-- AUTHORIZATION 
    This section sets the authorization policies of the 
    application. You can allow or deny access to application 
    resources by user or role. Wildcards: "*" mean everyone, 
    "?" means anonymous (unauthenticated) users.
  -->

  <authorization>
    <allow users="*" /> <!-- Allow all users -->
    <!-- 
    <allow users="[comma separated list of users]"
      roles="[comma separated list of roles]"/>
    <deny users="[comma separated list of users]"
      roles="[comma separated list of roles]"/>
    -->
  </authorization>

  <!-- APPLICATION-LEVEL TRACE LOGGING
    Application-level tracing enables trace log output for 
    every page within an application. 
    Set trace enabled="true" to enable application trace 
    logging. If pageOutput="true", the trace information 
    will be displayed at the bottom of each page. Otherwise, 
    you can view the application trace log by browsing the 
    "trace.axd" page from your web application root. 
  -->
  <trace
    enabled="false"
    requestLimit="10"
    pageOutput="false"
    traceMode="SortByTime"
    localOnly="true"
  />

  <!-- SESSION STATE SETTINGS
    By default ASP.NET uses cookies to identify which requests 
    belong to a particular session. If cookies are not available, 
    a session can be tracked by adding a session identifier to the 
    URL. To disable cookies, set sessionState cookieless="true".
  -->
  <sessionState 
    mode="InProc"
    stateConnectionString="tcpip=127.0.0.1:42424"
    sqlConnectionString="data source=127.0.0.1;Trusted_Connection=yes"
    cookieless="false" 
    timeout="20" 
  />

  <!-- GLOBALIZATION
    This section sets the globalization settings of the application. 
  -->
  <globalization 
    requestEncoding="utf-8" 
    responseEncoding="utf-8" 
  />
   
 </system.web>

</configuration>

Explanation

Lines necessary for BotDetect CAPTCHA to function properly have been bold, other lines are all standard values generated by Visual Studio 2003 by default. There are no special settings related to CAPTCHA randomization in the web.config file.

The <httpHandlers> element registers the path used for CAPTCHA image and sound requests for processing by Lanap.BotDetect.dll code, while the <sessionState> element declares the persistence mechanism used by BotDetect to keep the CAPTCHA codes and settings for each user.

You can use different Session State settings and modes depending on your application's needs, but you will have to ensure Session State persistence is available for BotDetect to work. Special care should be taken if you are running multiple load-balanced servers, as explained in this FAQ item.

[back to top]