How To Configure BotDetect CAPTCHA Options (BotDetect v3.0; deprecated)

BotDetect .NET Captcha allows detailed customization of many Captcha properties, both through the custom <botDetect> configuration section and application source code.

Beside the explanations on this page, you can also see how various Captcha properties have been set in the Captcha configuration code samples included in the BotDetect installation. You can reuse the sample source code (both C# and VB.NET versions are available) that fits your application requirements.

• BotDetect Captcha configuration mechanisms
  • BotDetect web.config configuration section
  • Captcha .aspx / Visual Studio designer instance settings
  • Captcha code-behind instance settings
  • Captcha event handler property setting and randomization
• BotDetect Captcha internationalization
  • Captcha locale setting
  • Captcha locale-dependent values
• BotDetect Captcha code settings
  • Captcha code style
  • Captcha code length
  • Custom Captcha code character sets
  • Captcha code timeout
  • Generated Captcha code filtering
  • Test mode
• BotDetect Captcha image settings
  • Captcha image style
  • Captcha image size
  • Captcha image format
  • Captcha image custom color scheme
• BotDetect audio Captcha sound settings
  • Captcha sound style
  • Captcha sound format
  • Disabling Captcha sound
  • Captcha sound package settings
  • Captcha sound icon
  • Captcha sound start delay
  • Captcha sound regeneration mode
• BotDetect Captcha reloading settings
  • Disabling Captcha reloading
  • Captcha reload icon
  • Captcha automatic reloading
• BotDetect Captcha web settings
  • Captcha user input processing
  • Captcha help link
  • Captcha tabindexes
  • Captcha icon layout
  • Captcha remote script
  • Captcha CSS styles
  • Captcha client-side events
  • Captcha Url settings
  • Captcha request filtering
  • Captcha encryption
  • Captcha HttpHandler troubleshooting
  • Captcha Session troubleshooting

BotDetect CAPTCHA ASPNET Configuration Mechanisms

BotDetect Captcha properties can be set in several different ways, depending on the type of value you are customizing.

BotDetect CAPTCHA Web.Config Configuration Section

BotDetect Captcha customization code sample coming with the BotDetect installation.

This configuration section first needs to be registered at the top of the web.config file:

<configuration>
  <configSections>
    <!-- Register the BotDetect configuration section -->
    <section name="botDetect" requirePermission="false" 
      type="BotDetect.Configuration.BotDetectConfigurationSection, BotDetect" />
  </configSections>

You can then create the <botDetect> section just below the closing </configSections> element, and (for example) disable all audio Captcha sounds in the application by specifying:

<botDetect>
  <captchaSound enabled="false" />
</botDetect>

[back to the top of the page]

BotDetect CAPTCHA .aspx / Visual Studio Designer Instance Settings

When adding the BotDetect:Captcha control to the .aspx file defining your form (either by using the Visual Studio Designer or editing the source directly), you can specify various attributes in the element declaration. For example, the simplest way to specify Captcha image size is:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" ImageSize="200, 50" />

However, it's not recommended to use this method to set all Captcha instance properties. Page source declarations are processed when the page is loaded, and since they have to be applied to Captcha images and sounds (which come as separate Http requests), they have to be saved in ASPNET Session state. It's better not to take up Session space if it's not necessary.

[back to the top of the page]

BotDetect CAPTCHA Code-Behind Instance Settings

It's also possible to specify various Captcha object settings in your page code-behind code. For example, code type and length can be set in the Page_PreRender override:

protected void Page_PreRender(object sender, EventArgs e)
{
  // initial page setup
  if (!IsPostBack)
  {
    // Captcha code properties
    SampleCaptcha.CodeLength = 4;
    SampleCaptcha.CodeType = BotDetect.CodeType.Numeric;
}

The same caveat applies to this method as with .aspx settings: this code is executed when the form is loaded, but since Captcha images and sounds are loaded in separate Http requests (which don't result in this code being executed), all values set this way have to be saved in ASPNET Session state. Since different visitors will use separate Sessions, the amount of state used is multiplied by the number of active visitors / Sessions, and it's better not to use a lot of it.

[back to the top of the page]

BotDetect CAPTCHA Event Handler Property Setting and Randomization

This is the recommended approach to Captcha instance property setting. It's the most complex method, since it requires setting up an event handler. But since this handler is going to be executed for all Captcha requests (including separate Captcha image and sound Http requests), there is no need to persist the values in ASPNET Session state.

Randomizing Captcha properties significantly improves Captcha security, and it should always be performed in this event handler instead of Page_Load or Page_PreRender, because the Captcha control event is also fired for direct Captcha image and sound requests (which skip the page events since the page is never loaded) – for example when clicking the Captcha reload button repeatedly.

You can see this approach to BotDetect Captcha property setting implemented in the Captcha randomization code sample coming with the BotDetect installation.

First, a InitializedCaptchaControl event handler needs to be registered in the Page_Init override:

protected void Page_Init(object sender, EventArgs e)
{
  SampleCaptcha.InitializedCaptchaControl += 
    new EventHandler<InitializedCaptchaControlEventArgs>(
      SampleCaptcha_InitializedCaptchaControl);
}

Then, randomization rules can be declared in the event handler:

void SampleCaptcha_InitializedCaptchaControl(object sender, 
  InitializedCaptchaControlEventArgs e)
{
  if (e.CaptchaId != SampleCaptcha.CaptchaId)
  {
    return;
  }

  CaptchaControl captcha = sender as CaptchaControl;

  // randomize code generation properties
  captcha.CodeStyle = CaptchaRandomization.GetRandomCodeStyle();
  captcha.CodeLength = CaptchaRandomization.GetRandomCodeLength(4, 5);
  captcha.ImageStyle = CaptchaRandomization.GetRandomImageStyle();
  captcha.SoundStyle = CaptchaRandomization.GetRandomSoundStyle();
}

The CaptchaRandomization helper allows easy randomization of Captcha parameters, as described in its documentation.

[back to the top of the page]

How to Use BotDetect Captcha Control Internationalization

BotDetect 3 supports Captcha localization, using character sets and sound pronunciation languages appropriate to the active locale setting.

BotDetect Captcha Control Locale Setting

Locale strings can be set through the instance Locale property. For example, you can set the Captcha locale in Page_Load depending on the language the user selected:

protected void Page_Load(object sender, EventArgs e)
{
  if (...) 
  {
    // Canadian English
    SampleCaptcha.Locale = "en-CA"; 
  }
  else
  {
    // Canadian French
    SampleCaptcha.Locale = "fr-CA";
  }
}

Locale strings can specify the language (for example en, ru, cmn, ...), charset (for example ja-Hira uses Japanese Hiragana characters, while ja-Kana uses Japanese Katakana characters) and country (for example en-US and en-GB differ in the pronunciation used).

For this to work, you have to choose a locale combination supported by BotDetect, and copy the appropriate pronunciation sound package to the Bin\BotDetectSounds subfolder of your application.

If you use a right-to-left locale setting like Arabic or Hebrew, you should also set the appropriate text direction on the textbox element used for Captcha code retyping:

<asp:TextBox ID="CaptchaCodeTextBox" runat="server" dir="rtl"></asp:TextBox>

Depending on your OS version and the locale you want to use, you also might have to install the appropriate Windows localization package, containing fonts supporting the required non-latin characters.

[back to the top of the page]

BotDetect Captcha Control Locale-Dependent Values

Several configurable BotDetect strings can be defined as locale-dependent, with the actual value used chosen among the configured values depending on the active locale setting. This is achieved by specifying a collection of localizedString elements, each with a regular expression value matching locales. The longest found matched key is used, and the element without the locale key (or an empty one) is the default.

Captcha Image Tooltip

Locale-dependent Captcha image tooltip / alt text can be specified in the <botDetect> configuration section:

<botDetect>
  <captchaImage>
    <!-- Custom Captcha image alt text / title -->
    <captchaImageTooltip>
      <localizedString value="CAPTCHA Image Custom Universal Tooltip" />
      <localizedString locale="es" 
        value="CAPTCHA Image Custom Spanish Tooltip" />
      <localizedString locale="es-MX" 
        value="CAPTCHA Image Custom Mexican Spanish Tooltip" />
    </captchaImageTooltip>

Captcha Sound Icon Tooltip

While sound icon image customizations are global, the sound icon title / alt text is locale-dependent:

<botDetect>
  <captchaSound>
    <!-- Custom sound Captcha icon titles -->
    <soundIcon>
      <soundIconTooltip>
        <localizedString value="Sound Icon Custom Universal Tooltip" />
        <localizedString locale="es" 
          value="Sound Icon Custom Spanish Tooltip" />
      </soundIconTooltip>

Captcha Reload Icon Tooltip

While reload icon image customizations are global, the reload icon title / alt text is locale-dependent:

<botDetect>
  <captchaReloading>
    <!-- Custom reload Captcha icon titles -->
    <reloadIcon>
      <reloadIconTooltip>
        <localizedString value="Reload Icon Custom Universal Tooltip" />
        <localizedString locale="es" 
          value="Reload Icon Custom Spanish Tooltip" />
      </reloadIconTooltip>

[back to the top of the page]

BotDetect CAPTCHA Code Settings

BotDetect exposes a number of settings which affect the randomly generated Captcha codes.

CAPTCHA Code Style

Captcha code style is usually set in the page code-behind.

captcha.CodeStyle = BotDetect.CodeStyle.Alpha;

[back to the top of the page]

CAPTCHA Code Length

Captcha code length is usually set in the page code-behind, and it's recommended that you randomize it(since it makes Ocr significantly harder).

captcha.CodeLength = CaptchaRandomization.GetRandomCodeLength(4, 5);

[back to the top of the page]

Custom CAPTCHA Code Character Sets

The character set used to generate BotDetect Captcha codes can also be customized. First, you can define a number of custom character sets in the <botDetect> configuration section:

<botDetect>
  <captchaCodes>
    <!-- Defines custom character sets for Captcha code generation.  
      You can then map the custom character sets defined here to 
      appropriate Captcha control  instances by name in code-behind 
      or .aspx designer. -->
    <characterSets>
      <!-- Full charset specification, defining all 3 code styles. -->
      <characterSet 
        name="CustomCharset1" 
        alpha="A,B,C,D,E" 
        numeric="1,2,3,4" 
        alphanumeric="A,B,C,D,1,2,3" />
      <!-- If you don't want to distinguish between code styles, 
        you can specify the alphanumeric characters only and they
        will be used for all Captcha codes regardless of codeStyle. -->
      <characterSet 
        name="CustomCharset2" 
        alphanumeric="A,B,C,D" />
    </characterSets>

You can then map pre-defined character sets to individual Captcha instances in application code:

// choose the custom charset used for CAPTCHA code generation
// (various custom charsets can be defined in the web.config file)
captcha.CustomCharacterSetName = "CustomCharset1";

[back to the top of the page]

CAPTCHA Code Timeout

Captcha codes can be set to expire after a user-defined period (in seconds) in the <botDetect> configuration section:

<botDetect>
  <captchaCodes timeout="300">

The Captcha can only be successfully solved within the specified time after generation. This is an optional security improvement that narrows the window of opportunity for attacks based on re-using the Captcha image on another site controlled by the attacker, or similar human-solver-based attacks on Captcha-protected forms.

The ASPNET Session timeout configured for the current application is used by default (if a value isn't specified). This setting is usually paired with the auto-reloading setting.

[back to the top of the page]

Generated CAPTCHA Code Filtering

BotDetect also allows you to filter certain unwanted sequences from randomly generated Captcha codes. This is useful for keeping your Captchas free of swear words and other potentially undesirable values. You can see how this works in the Captcha code filtering code sample included in the BotDetect installation.

The actual (case-insensitive) banned sequence list can be stored in any external storage you prefer:

• A .txt file with one banned sequence per line
• An .xml file with one banned sequence per Xml element
• A .config file <appSettings> element value attribute set to a comma-separated list of banned sequences
• A .csv file with one banned sequence per comma-separated-slot
• An SQL table in a custom database with one banned sequence per table row
• Etc.

The static BotDetect.Web.UI.Captcha.BannedSequences field takes a List<string> containing the banned sequence definitions, which should be read from the external storage on ASPNET application startup (i.e. the Application_Start event handler defined in Global.asax).

Since Captcha codes are generally short (usually between 3 and 8 characters long), it doesn't make sense to use a list of actual banned words, but simple "banned character sequences" which cover multiple undesirable values. For example, to prevent the random generator from using both "man" and "manners" in Captcha codes, it's enough to ban the "man" sequence.

[back to the top of the page]

CAPTCHA Test Mode

If you want to run automated tests that need to be able to submit a Captcha-protected form successfully in QA environments, you can turn on test mode with a simple configuration switch. It makes the Captcha trivially solvable (always using the "TEST" code instead of a random sequence of characters). Be careful not to enable this on production websites since it will allow trivial Captcha bypassing for bots, but will still provide an obstacle for human users.

<botDetect>
  <captchaCodes> 
    <testMode enabled="true"/>

[back to the top of the page]

BotDetect CAPTCHA Image Settings

BotDetect exposes a number of settings which affect Captcha image generation.

CAPTCHA Image Style

It's best to randomize the BotDetect Captcha image style in the InitializedCaptchaControl event handler, since that option provides the highest Captcha image security. You can choose a set of image styles that will randomly be used:

// use an image style randomly selected from the given subset
ImageStyle[] imageStyles = { 
  ImageStyle.Lego, 
  ImageStyle.MeltingHeat, 
  ImageStyle.Ghostly,
  ImageStyle.Fingerprints, 
  ImageStyle.Graffiti2, 
  ImageStyle.Bullets2,
  ImageStyle.CaughtInTheNet2, 
  ImageStyle.Collage, 
  ImageStyle.Chalkboard
};

captcha.ImageStyle = CaptchaRandomization.GetRandomImageStyle(imageStyles);

[back to the top of the page]

CAPTCHA Image Size

BotDetect Captcha image size can be set as a Captcha control attribute:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" ImageSize="200, 50" />

[back to the top of the page]

CAPTCHA Image Format

Since the Captcha image format won't change for different Captcha object instances, you can set it as a Captcha control attribute:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" ImageFormat="Png" />

[back to the top of the page]

CAPTCHA Image Custom Color Scheme

BotDetect allows color scheme customization though two color points: a custom dark color and a custom light color. Since many Captcha drawing styles randomize the actual color used, the user-defined values are used as randomization starting points instead of absolute values.

Furthermore, since some drawing styles use light text on a dark background, while other draw dark text on a light background, text and background colors are not set directly, but are referred to as simply the "dark" and the "light" color. This allows you to randomize the image drawing style, for example, and still keep a consistent color scheme adjusted to your website design.

The color are specified as System.Drawing.Color values, so you can use both predefined color names and custom color objects. For example, in page source you would use:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" CustomDarkColor="SeaGreen"

while in page code-behind you can use:

SampleCaptcha.CustomDarkColor = System.Drawing.Color.FromArgb(127, 63, 255);

[back to the top of the page]

BotDetect Audio CAPTCHA Sound Settings

BotDetect exposes a number of settings which affect audio Captcha sound generation.

Audio CAPTCHA Sound Style

BotDetect Captcha sound style is best randomized in the InitializedCaptchaControl event handler, since that option provides the highest audio Captcha sound security. You can choose a set of sound styles that will randomly be used:

// use a sound style randomly selected from the given subset
SoundStyle[] soundStyles = { 
  SoundStyle.Dispatch, 
  SoundStyle.Radio, 
  SoundStyle.Synth
};

captcha.SoundStyle = CaptchaRandomization.GetRandomSoundStyle(soundStyles);

[back to the top of the page]

Audio CAPTCHA Sound Format

Since the audio Captcha sound format won't change for different Captcha object instances, you can set it as a Captcha control attribute:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" 
  SoundFormat="WavPcm8bit8kHzMono" />

[back to the top of the page]

Disabling Audio CAPTCHA

Captcha sounds can be disabled entirely in the <botDetect> configuration section:

<botDetect>
  <captchaSound enabled="false" />

[back to the top of the page]

Audio CAPTCHA Sound Package Settings

Settings related to BotDetect sound packages apply to the whole application, and can be changed in the <botDetect> configuration section.

Sound Package Location

Instead of copying sound packages to each application's Bin folder, you can also load them from a central location. You just have to ensure the IIS worker process running your ASPNET application has permission to access the location, and specify it as:

<botDetect>
  <captchaSound>
    <soundPackages folderPath="C:\Program Files\Lanapsoft\
      BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds" />

When specifying custom SoundPackage locations, you can use:

• Absolute paths, as shown above
• Assembly-relative paths, e.g. "\BotDetectSounds" will look in the folder where the currently running BotDetect assembly was loaded from (your application's Bin folder)
• Application-relative paths, e.g. "~/BotDetectSounds" will look for BotDetectSounds in the application root folder

Missing Sound Package Behavior

When BotDetect can not find the pronunciation sound package required for the current locale settings, a warning is displayed by default. This helps during development and deployment, so you don't mistakenly forget to copy the needed files.

However, this warning is not meant for site visitors, so if you didn't copy a particular sound package because you don't want to support audio Captcha sounds in that language, you can disable the warning (and the sound icon for such locales) by specifying:

<botDetect>
  <captchaSound>
    <soundPackages warnAboutMissingSoundPackages="false" />

[back to the top of the page]

Audio CAPTCHA Sound Icon

BotDetect allows you to use a custom sound icon, which can be specified as an application-relative or an absolute Url. The default icon size is 22 x 22 pixels, and if your custom icon is smaller or larger, specifying its width will adjust the BotDetect layout to accommodate it.

<botDetect>
  <captchaSound>
    <soundIcon filePath="~/CustomSoundIcon.gif" iconWidth="22">

[back to the top of the page]

Audio CAPTCHA Sound Start Delay

BotDetect allows you to set the starting delay of audio Captcha JavaScript playback (in milliseconds). This can be useful for improving usability of the Captcha audio for blind people using JAWS or similar readers, which will read the label associated with the Captcha code textbox and start sound playback simultaneously when the sound icon is activated. Setting this delay to e.g. 2000 (2 seconds) will give the user time to hear both the pronounced label and the Captcha sound clearly:

<botDetect>
  <captchaSound startDelay="2000" />

[back to the top of the page]

Audio CAPTCHA Sound Regeneration Mode

How will multiple consecutive requests for audio Captcha with the same Captcha code ("sound regeneration") be handled by BotDetect - a trade-off of security, usability, and storage requirements.

<botDetect>
  <captchaSound enabled="true" startDelay="1000" regenerationMode="limited">

Sound Regeneration Mode	None	Limited	Unlimited
Security	★★★★★	★★★★☆	★☆☆☆☆
Usability	★★★★★	★★★★☆	★★★★★
Storage Requirements	★★★★★	★☆☆☆☆	★☆☆☆☆

Sound Regeneration Mode "None"

Generate only one sound response per Captcha code, cache it on the server, and serve it for all consecutive sound requests.

• High security: Comparative analysis of multiple sounds is impossible since only one sound response exists per Captcha code.
• High usability: Works consistently across all browsers, regardless of their Html5 audio support and without depending on JavaScript functionality.
• High storage requirements: The generated sound bytes must be stored in Session state, consuming server memory or other storage medium for each Captcha code requested as Captcha audio.

Sound Regeneration Mode "Limited"

Allow generation of a limited number of different sound responses (the minimum required to make Captcha audio work in all supported client browsers and devices), and automatically change the Captcha code on the client for consecutive sound requests if needed and possible.

• Good security: Comparative analysis of multiple sounds is severely hampered, since the small number of sound responses available does not provide enough information to seriously undermine Captcha security.
• Good usability: Since Captcha sound will only be served a small number of times for the same Captcha code (returning an error after the limit has been hit), observed behavior depends on client browser capabilities:
  • Modern Html5 Wav audio compatible browsers will always replay the same sound on consecutive sound icon clicks, without requesting a regenerated sound from the server.
  • Older browsers without support for client-side audio replay must detect consecutive sound icon clicks that might trigger the sound regeneration limit on the server and automatically change the Captcha code (by reloading the Captcha image) to ensure sound will play properly. For each sound icon click after the first one, the Captcha image will be changed before audio is played.
  • Browsers without JavaScript capability (and bots) will have to reload the form to get a new Captcha code to make the sound work again after the regeneration limit had been hit.
• Low storage requirements: Generated sound responses don't need to be stored on the server.

Sound Regeneration Mode "Unlimited"

Each audio request will generate a new Captcha sound response (previous BotDetect version behavior).

• Low security: Comparative analysis of multiple sounds for the same Captcha code allows for higher accuracy of automated recognition.
• High usability: Works consistently across all browsers, regardless of their Html5 audio support and without depending on JavaScript functionality.
• Low storage requirements: Generated sound responses don't need to be stored on the server.

Considerations

BotDetect defaults to limited sound regeneration as the most reasonable overall trade-off. At user discretion, higher security and usability can be achieved at the cost of significant amounts of server-side storage space. Unlimited sound regeneration is not recommended due to low security, but is left as an option for backwards-compatibility.

[back to the top of the page]

BotDetect CAPTCHA Reloading Settings

BotDetect exposes a number of settings which affect Captcha reloading behavior.

Disabling CAPTCHA Reloading

Captcha reloading can be disabled entirely in the <botDetect> configuration section:

<botDetect>
  <captchaReloading enabled="false" />

[back to the top of the page]

CAPTCHA Reload Icon

BotDetect allows you to use a custom reload icon, which can be specified as an application-relative or an absolute Url. The default icon size is 22 x 22 pixels, and if your custom icon is smaller or larger, specifying its width will adjust the BotDetect layout to accommodate it.

<botDetect>
  <captchaReloading>
    <reloadIcon filePath="https://captcha.com/images/refresh.png"
      iconWidth="17">

[back to the top of the page]

CAPTCHA Automatic Reloading

Captcha images are automatically reloaded when the Captcha code expires (as defined by the code timeout), but only within a certain interval from their first generation.

This allows you to have a short Captcha code timeout (e.g. 5 minutes) to narrow the window of opportunity for Captcha reusing on other sites or human-solver-powered bots, and actual visitors can still fill out your form at their own pace and without rushing (since the Captcha image will be reloaded automatically when it is no longer valid).

Since we don't want infinite sessions when the user leaves the form open in a background browser tab over the weekend (for example), you should also set a reasonable upper limit on the auto-reload period (e.g. 2 hours = 7200 seconds).

<botDetect>
  <captchaReloading enabled="true">
    <autoReloadExpiredCaptchas enabled="true" timeout="7200" />

[back to the top of the page]

BotDetect CAPTCHA Web Settings

BotDetect exposes a number of settings which affect the Captcha Html markup, client-side behavior, and Http behavior.

CAPTCHA User Input Processing

The Captcha user input textbox client ID can be registered for each Captcha control instance in code-behind or the .aspx designer:

SampleCaptcha.UserInputClientID = CaptchaCodeTextBox.ClientID;

Several client-side behaviors are enabled by default when this is done, which can optionally be disabled in the <botDetect> configuration section:

<botDetect>
  <captchaUserInput 
    autoUppercase="false" 
    autoClear="false" 
    autoFocus="false" />

autoUppercase

Anything the users type in the input textbox will be uppercased on the fly, since Captcha validation is not and should not be case-sensitive. This is a small usability improvement that helps communicate that fact to the users clearly.

autoClear

The input textbox will be cleared on all Reload icon clicks and auto-reloads, since any previous input in the textbox will be invalidated by Captcha reloading. This is a small usability improvement that helps users avoid having to delete the previous input themselves.

autoFocus

The input textbox will be assigned focus on all Captcha Sound and Captcha Reload icon clicks, allowing the users to more easily type in the code as they hear it or as the new image loads. This does not apply to auto-reloading of expired Captchas, since the user might be filling out another field on the form when the auto-reload starts and shouldn't be distracted.

[back to the top of the page]

Captcha Help Link

The Captcha markup can include a link leading to a locale-specific Captcha help page. The help link is added to Captcha image markup, so its settings are placed withing the <captchaImage> configuration element:

<botDetect>
  <captchaImage>
    <helpLink enabled="true" mode="text">
      <helpPage>
        <!-- absolute or application-relative help page Urls -->
        <localizedString value="~/captcha.html" />
        <localizedString locale="es" 
          value="http://es.captcha.com/captcha.html" />
      </helpPage>
      <!-- text used in the help link -->
      <helpText>
        <localizedString value="Custom CAPTCHA Help Link Text" />
        <localizedString locale="es" 
          value="Custom Spanish CAPTCHA Help Link Text" />
      </helpText>
    </helpLink>

The help link can be controlled with four settings: enabled, mode, helpPage and helpText.

enabled

The help link is turned on by default, and this settings allows disabling it completely (enabled="false"). Please note that this setting is ignored in the free version of BotDetect.

mode

There are two modes of rendering the Captcha help link available:

1. mode="image": the Captcha image is a link to the help page; clicking the Captcha image opens the help page in a new browser tab. This mode takes less space, but can lead to accidental clicks (particularly by mobile visitors).
2. mode="text": a text link to the help page is rendered in the bottom 10 px of the Captcha image. This mode makes the Captcha help link more explicit, but reduces the effective height of Captcha images by 10px. If this makes the Captcha images less readable, you can compensate by increasing the Captcha image height.

helpPage

The Captcha help link points to a locale-dependent help page, which can be set as an absolute or relative Url of the page in the usual manner of Captcha locale-dependent strings. Please note that this setting is ignored in the free version of BotDetect.

helpText

The text used in the Captcha help link, added to the text link or as the tooltip of the image link (depending on the help link mode used). Can be a Captcha locale-dependent string. Please note that the text set needs to contain at least 4 non-whitespace characters in the free version of BotDetect.

[back to the top of the page]

CAPTCHA Tabindexes

You can set the starting tabindex used for Captcha Html elements through a Captcha control property:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" TabIndex="12" />

The keyboard-selectable Captcha markup elements are: the Captcha reload icon, the Captcha sound icon, and (only in the Free version of BotDetect) the BotDetect website link.

Depending on your settings (is Captcha reloading enabled, are Captcha sounds enabled) and the version of BotDetect you are using (free or paid), the next available tabindex on the page can be from 0 to 3 greater than this value.

To disable tabbing over Captcha elements in most browsers, set the TabIndex property to -1:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" TabIndex="-1" />

[back to the top of the page]

CAPTCHA Remote Script Configuration

By default, BotDetect also adds a remote JavaScript include (remote.captcha.com/include.js) loaded from the captcha.com server, which is currently used only for stats, but is planned to develop into additional Captcha functionality. This include can be disabled in BotDetect configuration:

<captchaRemoteScript enabled="false" />

Please note that this setting is ignored in the free version of BotDetect.

[back to the top of the page]

CAPTCHA Icon Layout

By default, BotDetect tries to adjust the built-in icons to the Captcha image height, switching to smaller (17 x 17 px) icons if the image is less than 50 pixels tall, and displaying the icons horizontally instead of vertically if the image is less than 40 pixels tall.

You can override this default behavior using several Captcha object instance properties:

• Setting UseSmallIcons allows you to control whether BotDetect uses the smaller built-in icons.
• Setting UseHorizontalIcons allows you to control whether BotDetect displays the icons one next to the other (instead of one below the other).
• If you're using custom icons, setting their widths in the configuration file will automatically scale the BotDetect layout to them. In case you need to override the default layout code calculations (when using a completely custom icon layout), the IconsDivWidth property controls the related size.

[back to the top of the page]

CAPTCHA CSS Styles

You can write your own custom stylesheet which overrides the existing BotDetect styles. As long as it's included in the page after the default stylesheets (so it applies last), it should be possible to override any existing style declaration.

The default declarations can be seen in the BotDetect layout stylesheet loaded from the BotDetectCaptcha.ashx?get=layoutStyleSheet path on the page.

If your declarations need to override an existing style declaration, using the !important keyword in your declarations might be needed.

You can also assign a custom CSS class name to the Captcha control, which will apply to the top-most <div> element of the generated Html markup:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" CssClass="CustomClassName" />

If you need to dynamically add inline style declarations to the top-most <div> element of Html markup generated by the Captcha control, you can do so in page code-behind:

SampleCaptcha.Style.Add("float", "left");

[back to the top of the page]

CAPTCHA Client-Side Events

BotDetect includes a custom client-side event system, allowing you to specify your own client-side handlers for certain BotDetect actions.

For example, you would add your handler to the BotDetect.PostReloadImage client-side event by using:

BotDetect.RegisterCustomHandler('PostReloadImage',
  function() {
    // your code goes here
  }
);

[back to the top of the page]

CAPTCHA Url Settings

BotDetect allows you to change the path used for the Captcha HttpHandler, in case the default BotDetectCaptcha.ashx doesn't suit your application. You can customize both the filename and the extension, but you must ensure the IIS mapping for the custom extension is set to be processed by the ASPNET runtime.

<botDetect>
  <captchaUrls requestPath="CaptchaCustomPath.ashx" />

You also have to update all HttpHandler registrations to match the new value.

Note that BotDetect uses relative paths by default, and will make HttpHandler requests with the same application-relative path as the page it's placed on. If you prefer all BotDetect requests to go to the application root folder, use: requestPath="~/CaptchaCustomPath.ashx"

[back to the top of the page]

CAPTCHA Request Filtering

BotDetect by default includes some basic Http request filtering, allowing only a certain number of repeated requests with identical querystrings. Human users in normal browsers will always use unique querystrings to access Captcha images and sounds (the way the Captcha control works guarantees this), while simple bots will often repeat the same request in short time intervals.

This is a simple measure that increases Captcha security by stopping to serve Captcha images and sounds to such obvious bots (Captcha is used for bot detection, and in such a case we can detect that a bot is involved even without wasting resources on generating more Captcha images or sounds).

In case you want to turn off or modify this behavior, you can use the <botDetect> configuration section value:

<botDetect>
  <captchaRequestFilter 
    enabled="true" 
    allowedRepeatedRequests="10" />

[back to the top of the page]

CAPTCHA Encryption

The SessionID values that has to be passed in sound Captcha querystrings to avoid sound mismatch problems in some older browsers (an optional but recommended improvement, as explained in the BotDetect FAQ) are never passed in plaintext querystring to avoid Session hijacking or spoofing attacks.

To secure them properly, you should specify your own unique encryption password:

<botDetect>
  <captchaEncryption 
    encryptionPassword="TODO:SecretEncryptionPassword" />

[back to the top of the page]

CAPTCHA HttpHandler Troubleshooting

Since the BotDetect HttpHandler must be properly registered for Captcha images to show, there is a piece of diagnostic code that tries to detect is the HttpHandler registered in the current ASPNET application.

If it's not (requests for BotDetectCaptcha.ashx paths return a 404 Not Found error), an error message is shown on the page.

Once you've ensured the Captcha HttpHandler works properly, you can turn this detection off by specifying:

<botDetect>
  <captchaHttpHandlerTroubleshooting enabled="false" />

[back to the top of the page]

CAPTCHA Session Troubleshooting

Since ASPNET Session state problems are the most common reason users experience BotDetect issues, BotDetect v3 includes a simple helper used for Session state troubleshooting, which detects the following conditions:

• Is the ASPNET Session HttpModule running (full trust only)
• Is the BotDetect CustomSessionIdManager included (full trust only)
• Is Session State empty
• Is a new Session started(on PostBack and all HttpHandler requests)
• Is the Captcha persistence empty (for initialized CaptchaControls only)

If any of these conditions is detected, a warning message is shown on the page. This helps detect and resolve ASPNET Session state issues, but should ideally only be running while you're testing your application.

Once you've ensured ASPNET Session state works properly for Captcha persistence purposes, you can turn this detection off by specifying:

<botDetect>
  <captchaSessionTroubleshooting enabled="false" />

[back to the top of the page]