BotDetect ASP.NET CAPTCHA Configuration Options



BotDetect ASP.NET Captcha allows user customization of over 40 Captcha properties controlling many aspects of Captcha challenge behavior and appearance.

CAPTCHA Code Length

Description

Number of characters in randomly generated Captcha codes (answers to Captcha challenges).

Default

The default value is random (4-6 characters).

Valid User Setting Values

Valid user Captcha code length setting values are integers larger than 0 and smaller than 16.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect codeLength="4" 
or
<botDetect codeLength="3-5" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.CodeLength = 4; 
or
ExampleCaptcha.CodeLength = CaptchaRandomization.GetRandomCodeLength(3, 5); 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "CodeLength": 6
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" code-length="4"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" CodeLength="4" 

Remarks

It is recommended to always randomize Captcha code length since it significantly increases Captcha security vs. automated analysis. To ensure randomization really affects each Captcha challenge generated, it should be performed through the application configuration file or user code executing for each Captcha challenge generation Http request. Randomization performed through Captcha object instance properties in form processing source code will only execute (and re-calculate the value used) on form GET or POST requests, instead on every Captcha challenge (image or sound) generation Http request.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Code Style

Description

Character types used to generate random Captcha codes.

Default

The default value is Alphanumeric.

Valid User Setting Values

Valid user Captcha code style setting values are members of the BotDetect CodeStyle enumeration (Alpha, Numeric, or Alphanumeric).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect codeStyle="alpha" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.CodeStyle = CodeStyle.Alpha; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "CodeStyle": "Alpha"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" code-style="Alpha"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" CodeStyle="Alpha" 

Remarks

Since entropy of the Captcha challenge depends on character set size to the power of Captcha code length, alpha codes should be slightly longer than alphanumeric ones (while numeric Captcha codes should be significantly longer) to achieve an appropriate level of Captcha security.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Disallowed Code Substrings

Description

Strings that should never occur in randomly generated Captcha codes. Can be both single characters (allows Captcha character set customization) and sequences of two or more characters (useful for swear words filtering, avoiding particular hard-to-read sequences etc.).

Default

The default value is empty (Captcha code filtering is optional).

Valid User Setting Values

Valid user disallowed Captcha code substring setting values are lists of arbitrary strings, in list object or CSV format. Whitespace is ignored, and disallowed substrings are not case-sensitive (because Captcha codes are case-insensitive as well).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect disallowedCodeSubstrings="x,y,z,mm,nn,oo,abc,bca,cab,todo" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.DisallowedCodeSubstringsCsv = "X,Y,Z,MM,NN,OO,ABC,BCA,CAB,TODO"; 
or
ExampleCaptcha.DisallowedCodeSubstringsList = 
  new List<string> { "X", "Y", "Z", "MM", "NN", "OO", "ABC", "BCA", "CAB", "TODO" }; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "DisallowedCodeSubstringsCsv": "X,Y,Z,MM,NN,OO,ABC,BCA,CAB,TODO"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" disallowed-code-substrings-csv="X,Y,Z,MM,NN,OO,ABC,BCA,CAB,TODO"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    DisallowedCodeSubstringsCsv="X,Y,Z,MM,NN,OO,ABC,BCA,CAB,TODO" 

Remarks

The character set used for Captcha code generation is automatically chosen based on Captcha locale. Since each character needs to have its pronunciation recorded and available to BotDetect code, expanding that default character set to include new characters is not supported (it would break Captcha sound functionality). However, if a particular character is found hard to read, it can easily be excluded from randomly generated Captcha codes.

Furthermore, offensive or otherwise undesirable words and character sequences can be banned. Since Captcha codes are generally short, it doesn't make sense to use an actual dictionary of words, but simple short sequences that cover multiple disallowed values. E.g. to prevent the random generator from using both 'man', 'manners' and 'mannequin' in Captcha codes, it's enough to ban the 'man' sequence.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Code Timeout

Description

The time period after random Captcha code generation during which Captcha challenges based on it can be solved: when it expires, even correct inputs will be considered as invalid submissions.

Default

The default value is 1200 seconds (20 minutes).

Valid User Setting Values

Valid user Captcha code timeout setting values are integers larger than 30 and smaller than 7200 (i.e. between half a minute and 2 hours).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect codeTimeout="600" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.CodeTimeout = 600; // 10 minutes 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "CodeTimeout": 600
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" code-timeout="600"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" CodeTimeout="600" 

Remarks

Reducing the Captcha code timeout is an optional security improvement that narrows the window of opportunity for attacks based on reusing the Captcha challenge on another site controlled by the attacker, proxying it to human solvers, or similar attempts to bypass the Captcha protection. However, to meet usability criteria, users filling out the form should always be given reasonably enough time to solve the Captcha challenge.

Since Captcha codes are stored in Session state by default, please note that if the configured code timeout is longer than the active Session timeout, Captcha validation will still fail if the user Session expires due to inactivity.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Test Mode Enabled

Description

Application configuration switch to use if you want to run automated tests that need to be able to submit a Captcha-protected form in QA environments.

Default

The default value is false.

Valid User Setting Values

Valid user Captcha test mode setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect testModeEnabled="true" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "TestModeEnabled": true
  }
}

Remarks

This setting is only supported in paid versions of BotDetect.

When test mode is enabled, it makes the Captcha challenge trivially solvable (always using "TEST" as the solution instead of a random sequence of characters). Be careful NEVER to enable this on production websites by mistake, since it will allow bots to trivially bypass the Captcha, but will still provide an obstacle for human users.

Because of the serious security implications if the Captcha test mode setting is misapplied, it can only be enabled globally for the whole application (individual forms and Captcha object instances can't change it), and will display a warning in generated Captcha container markup.

CAPTCHA Image Style

Description

The BotDetect drawing algorithm used to render Captcha codes in image Captcha challenges.

Default

The default value is random (an image style is chosen from all available values for each Captcha image generated).

Valid User Setting Values

Valid user Captcha image style setting values are members of the BotDetect ImageStyle enumeration. Please note that some image styles are restricted to paid versions of BotDetect, and will be ignored in free version implementations.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect imageStyle="SunAndWarmAir" 
or
<botDetect imageStyle="Chipped,Fingerprints,Graffiti,Bullets" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ImageStyle = ImageStyle.SunAndWarmAir; 
or
ImageStyle[] imageStyles = 
{ 
    ImageStyle.Chipped, 
    ImageStyle.Fingerprints, 
    ImageStyle.Graffiti, 
    ImageStyle.Bullets 
};
ExampleCaptcha.ImageStyle = CaptchaRandomization.GetRandomImageStyle(imageStyles);

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ImageStyle": "Chipped,Fingerprints,Graffiti,Bullets"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" image-style="SunAndWarmAir"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" ImageStyle="SunAndWarmAir" 

Remarks

It's best to randomize the Captcha image style, since randomly choosing a style for each Captcha image generated provides the highest level of Captcha security against automated OCR analysis. To ensure randomization really affects each Captcha challenge generated, it should be performed through the application configuration file or user code executing for each Captcha challenge generation Http request. Randomization performed through Captcha object instance properties in form processing source code will only execute (and re-calculate the value used) on form GET or POST requests, instead on every Captcha challenge (image or sound) generation Http request.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Image Size

Description

Size of Captcha image challenges generated.

Default

The default value is 250 x 50 pixels.

Valid User Setting Values

Valid user Captcha image size setting values are integers: widths can be between 20 and 500 pixels and heights between 20 and 200 pixels.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect imageWidth="120" imageHeight="35" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ImageSize = new System.Drawing.Size(120, 35); 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ImageWidth": 120,
    "ImageHeight": 35
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" image-width="120" image-height="35"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" ImageSize="120,35" 

Remarks

To keep Captcha images reasonably readable, their width:height ratio should be approximately the same as the average Captcha code length.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Image Format

Description

Image format in which Captcha images will be generated and sent to the client.

Default

The default value is Jpeg.

Valid User Setting Values

Valid user Captcha image format setting values are members of the BotDetect ImageFormat enumeration (Jpeg, Png, Gif).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect imageFormat="png" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ImageFormat = ImageFormat.Png; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ImageFormat": "Png"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" image-format="Png"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" ImageFormat="Png" 

Remarks

Please note that some Captcha image styles will result in low-quality (pixelated) images when the image format is set to Gif, due to randomized color schemes and use of color gradients. When switching image formats, please take care to check the impact on Captcha image readability.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Image Color Mode

Description

Image color mode in which Captcha image color will be rendered and change it to other color on hover.

Default

The default value is None in free versions and Grayscale in paid versions of BotDetect.

Valid User Setting Values

Valid user Captcha image color mode setting values are members of the BotDetect ImageColorMode enumeration (Color, Grayscale, None).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect imageColorMode="Grayscale" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ImageColorMode = ImageColorMode.Grayscale; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ImageColorMode": "Grayscale"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" image-color-mode="Grayscale"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" ImageColorMode="Grayscale" 

Remarks

This setting is only supported in paid versions of BotDetect.

Image Color Mode Color

Captcha image is rendered in color, and it becomes greyscale on hover.

Image Color Mode Grayscale

Captcha image is rendered in grayscale, and it becomes color on hover.

Image Color Mode None

Captcha image is still rendered in color by default and nothing happens on hover.

CAPTCHA Custom Colors

Description

BotDetect allows Captcha image color scheme customization though two color points: a custom dark color and a custom light color.

Default

The default values are empty (Captcha color customization is optional).

Valid User Setting Values

Valid user Captcha custom dark / light color setting values are Html colors, so you can use both predefined color names and custom color hex values.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect customDarkColor="DarkGreen" customLightColor="AliceBlue" 
or
<botDetect customDarkColor="#483d8b" customLightColor="#87cefa" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.CustomDarkColor = System.Drawing.Color.DarkGreen;
ExampleCaptcha.CustomLightColor = System.Drawing.Color.AliceBlue; 
or
ExampleCaptcha.CustomDarkColor = System.Drawing.Color.FromArgb(127, 63, 255);
ExampleCaptcha.CustomLightColor = System.Drawing.Color.FromArgb(230, 230, 255); 
or
ExampleCaptcha.CustomDarkColor = System.Drawing.ColorTranslator.FromHtml("#483d8b");
ExampleCaptcha.CustomLightColor = System.Drawing.ColorTranslator.FromHtml("#87cefa"); 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "CustomDarkColor": "#483d8b",
    "CustomLightColor": "#87cefa"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" custom-dark-color="#483d8b" custom-light-color="#87cefa"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    CustomDarkColor="DarkGreen" CustomLightColor="AliceBlue" 

Remarks

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.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Disabled Image Styles

Description

Application configuration setting that allows centralized temporary disabling of individual BotDetect image styles if there is ever an urgent issue that requires it.

Default

The default value is empty (image style disabling is an optional feature meant for short-term use during exceptional situations).

Valid User Setting Values

Valid user disabled image styles setting values are CSV strings of ImageStyle names (case-insensitive, separator whitespace is ignored).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect disabledImageStyles="Chipped,Lego,Wave" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "DisabledImageStyles": "Chipped,Lego,Wave"
  }
}

Remarks

BotDetect image styles used on user forms can be configured in different ways (a single static value, a randomized value, a dynamic value that adapts to visitor behavior) and can apply to all Captcha instances in an application or be specific to a particular Captcha challenge placed on a single form.

If an urgent issue is ever discovered in a BotDetect image style implementation (e.g. a bug causing it to throw errors in certain circumstances, or a weakness allowing some forms of automated analysis to bypass it, or a memory leak etc.), users should be able to deactivate the problematic ImageStyle while they're waiting for issue resolution.

This BotDetect setting acts as a centralized application configuration switch which allows such image style deactivation, without requiring users to examine and possibly modify all of their source code that might be affected. It also makes it much easier to revert the change later when the issue gets fixed.

CAPTCHA Sound Enabled

Description

Is Captcha sound enabled.

Default

The default value is true.

Valid User Setting Values

Valid user Captcha sound enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundEnabled="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundEnabled = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundEnabled": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-enabled="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" SoundEnabled="false" 

Remarks

Captcha sound can be disabled entirely (for example if you are using the free version of BotDetect, which only supports demo sound that is not actually accessible to human visitors) by setting this property to false.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Sound Style

Description

The BotDetect audio generation algorithm used to pronounce Captcha codes in sound Captcha challenges.

Default

The default value is random (a sound style is chosen from all available values for each Captcha sound generated).

Valid User Setting Values

Valid user Captcha sound style setting values are members of the BotDetect SoundStyle enumeration. Please note that some sound styles are restricted to paid versions of BotDetect, and will be ignored in free version implementations.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundStyle="Radio" 
or
<botDetect soundStyle="Dispatch,RedAlert,Synth" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundStyle = SoundStyle.Radio; 
or
SoundStyle[] soundStyles = 
{ 
    SoundStyle.Dispatch, 
    SoundStyle.RedAlert, 
    SoundStyle.Synth
};
ExampleCaptcha.SoundStyle = CaptchaRandomization.GetRandomSoundStyle(soundStyles);

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundStyle": "Dispatch,RedAlert,Synth"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-style="Radio"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" SoundStyle="Radio" 

Remarks

It's best to randomize the Captcha sound style, since randomly choosing a style for each Captcha sound generated provides the highest level of Captcha security against automated audio analysis and voice recognition. To ensure randomization really affects each Captcha challenge generated, it should be performed through the application configuration file or user code executing for each Captcha challenge generation Http request. Randomization performed through Captcha object instance properties in form processing source code will only execute (and re-calculate the value used) on form GET or POST requests, instead on every Captcha challenge (image or sound) generation Http request.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Sound Format

Description

Audio format in which Captcha sounds will be generated and sent to the client.

Default

The default value is WavPcm16bit8kHzMono.

Valid User Setting Values

Valid user Captcha sound format setting values are members of the BotDetect SoundFormat enumeration (WavPcm16bit8kHzMono, WavPcm8bit8kHzMono).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundFormat="WavPcm8bit8kHzMono" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundFormat = SoundFormat.WavPcm8bit8kHzMono; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundFormat": "WavPcm8bit8kHzMono"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-format="WavPcm8bit8kHzMono"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    SoundFormat="WavPcm8bit8kHzMono" 

Remarks

Using 8 bit sound instead of default 16 bits per example lowers the WAV file download size, but reduces sound quality.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Sound Regeneration Mode

Description

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

Default

The default value is Limited.

Valid User Setting Values

Valid user Captcha sound regeneration mode setting values are members of the BotDetect SoundRegenerationMode enumeration (None, Limited, Unlimited).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundRegenerationMode="None" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundRegenerationMode = SoundRegenerationMode.None; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundRegenerationMode ": "None"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-regeneration-mode="None"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    SoundRegenerationMode="None" 

Remarks

BotDetect defaults to limited sound regeneration as the most reasonable overall trade-off. At user discretion, higher security and usability can be achieved by disabling sound regeneration 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.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

Sound Regeneration Mode Option Details

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.

CAPTCHA Sound Packages Folder

Description

Application configuration setting controlling the file system location of BotDetect sound resources required for Captcha audio.

Default

The default value is the Bin\BotDetectSounds subfolder in your ASP.NET application folder.

Valid User Setting Values

Valid user Captcha sound packages folder setting values are absolute file system paths (starting with a drive identifier e,g, "C:\"), network paths (starting with "\\"), or relative paths based on the application root folder (starting with "~\") or the BotDetect assembly location (starting with "\").

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundPackagesFolder="C:\SharedResources\BotDetectSounds" 
or
<botDetect soundPackagesFolder="~\BotDetectSounds" 
or
<botDetect soundPackagesFolder="\BotDetectSounds" 
or
<botDetect soundPackagesFolder="\\NetworkShare\BotDetectSounds" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundPackagesFolder": "~\BotDetectSounds"
  }
}

Remarks

You should also always ensure that the IIS worker process running your ASP.NET application has permissions to read from the custom folder path.

Warn About Missing CAPTCHA Sound Packages

Description

Application configuration setting that controls whether BotDetect disables (greys-out and prevents clicks on) the Captcha sound icon and displays a warning tooltip when the sound package file containing character pronunciations for the currently set Captcha locale can not be found.

Default

The default value is true (display a warning when the required .bdsp file cannot be found).

Valid User Setting Values

Valid user warn about missing sound packages setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect warnAboutMissingSoundPackages="false" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "WarnAboutMissingSoundPackages": false
  }
}

Remarks

Warnings about missing sound packages help during development and deployment, so you don't mistakenly forget to download and copy the needed files. However, this warning is not meant for (and should never be seen by) site visitors. So if you didn't copy a particular sound package because you intentionally don't want to support audio Captcha sounds in that language, you can disable the warning (and the sound icon for such locales).

CAPTCHA Disabled Sound Styles

Description

Application configuration setting that allows centralized temporary disabling of individual BotDetect sound styles if there is ever an urgent issue that requires it.

Default

The default value is empty (sound style disabling is an optional feature meant for short-term use during exceptional situations).

Valid User Setting Values

Valid user disabled sound styles setting values are CSV strings of SoundStyle names (case-insensitive, separator whitespace is ignored).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect disabledSoundStyles="RedAlert,HiveMind" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "DisabledSoundStyles": "RedAlert,HiveMind"
  }
}

Remarks

BotDetect sound styles used on user forms can be configured in different ways (a single static value, a randomized value, a dynamic value that adapts to visitor behavior) and can apply to all Captcha instances in an application or be specific to a particular Captcha challenge placed on a single form.

If an urgent issue is ever discovered in a BotDetect sound style implementation (e.g. a bug causing it to throw errors in certain circumstances, or a weakness allowing some forms of automated analysis to bypass it, or a memory leak etc.), users should be able to deactivate the problematic SoundStyle while they're waiting for issue resolution.

This BotDetect setting acts as a centralized application configuration switch which allows such sound style deactivation, without requiring users to examine and possibly modify all of their source code that might be affected. It also makes it much easier to revert the change later when the issue gets fixed.

CAPTCHA Locale

Description

Captcha locale string, determining the exact character set used for random Captcha code generation and the pronunciation language used for sound Captcha generation.

Default

The default value is en-US.

Valid User Setting Values

Valid user Captcha locale setting values are composed of ISO language codes (for example en, ru, cmn, ...), charset codes (for example ja-Hira uses Japanese Hiragana characters, while ja-Kana uses Japanese Katakana characters) and country codes (for example en-US and en-GB differ in the pronunciation used).

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect locale="en-GB" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.Locale = "en-GB"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "Locale": "en-GB"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" locale="en-GB"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" Locale="en-GB" 

Remarks

Check the BotDetect localization page to find the list of currently supported locales, and download the pronunciation resources required for Captcha sounds.

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 (dir="rtl").

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.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA Image Tooltip

Description

The alternative text of the Captcha image Html element.

Default

The default value is "Retype the CAPTCHA code from the image".

Valid User Setting Values

Valid user Captcha image tooltip setting values are arbitrary strings.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect imageTooltip="Custom Captcha image tooltip" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ImageTooltip = "Custom Captcha image tooltip"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ImageTooltip": "Custom Captcha image tooltip"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" image-tooltip="Custom Captcha image tooltip"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    ImageTooltip="Custom Captcha image tooltip" 

CAPTCHA Sound Tooltip

Description

Tooltip of the Captcha sound icon.

Default

The default value is "Speak the CAPTCHA code".

Valid User Setting Values

Valid user Captcha sound tooltip setting values are arbitrary strings.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundTooltip="Custom Captcha sound icon tooltip" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundTooltip = "Custom Captcha sound icon tooltip"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundTooltip": "Custom Captcha sound icon tooltip"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-tooltip="Custom Captcha sound icon tooltip"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    SoundTooltip="Custom Captcha sound icon tooltip" 

CAPTCHA Reload Tooltip

Description

Tooltip of the Captcha reload icon.

Default

The default value is "Change the CAPTCHA code".

Valid User Setting Values

Valid user Captcha reload tooltip setting values are arbitrary strings.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect reloadTooltip="Custom Captcha reload icon tooltip" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ReloadTooltip = "Custom Captcha reload icon tooltip"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ReloadTooltip": "Custom Captcha reload icon tooltip"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" reload-tooltip="Custom Captcha reload icon tooltip"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    ReloadTooltip="Custom Captcha reload icon tooltip" 

Description

Text or tooltip of the Captcha help link, depending on help link mode.

Default

The default value depends on the width of the Captcha image.

Valid User Setting Values

Valid user Captcha help link setting values are strings at least 4 characters long.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect helpLinkText="Custom Captcha help link text" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.HelpLinkText = "Custom Captcha help link text"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HelpLinkText": "Custom Captcha help link text"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" help-link-text="Custom Captcha help link text"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    HelpLinkText="Custom Captcha help link text" 

Description

Url of the localized Captcha help page the help link points to.

Default

The default value depends on Captcha locale.

Valid User Setting Values

Valid user Captcha help link url setting values are absolute or relative Urls.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect helpLinkUrl="custom-captcha-help-page.html" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.HelpLinkUrl = "custom-captcha-help-page.html"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HelpLinkUrl": "custom-captcha-help-page.html"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" help-link-url="custom-captcha-help-page.html"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    HelpLinkUrl="custom-captcha-help-page.html" 

Remarks

This setting is only supported in paid versions of BotDetect.

CAPTCHA Reload Enabled

Description

Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled.

Default

The default value is true.

Valid User Setting Values

Valid user Captcha reload enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect reloadEnabled="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ReloadEnabled = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ReloadEnabled": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" reload-enabled="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" ReloadEnabled="false" 

Remarks

Requesting a new Captcha challenge on the current form requires client-side scripting, so the reload icon is only shown in browsers that have JavaScript enabled. When JavaScript is disabled or unsupported, the visitor can still get a different Captcha challenge by reloading the form.

Use Small CAPTCHA Icons

Description

Default BotDetect Captcha icons are 22x22 pixels large, but there is also a smaller set of 17x17 px icons used when the default ones are too large. This settings allows you to control which icon set will be used.

Default

The default value is true when the Captcha image height is < 50px, and false otherwise.

Valid User Setting Values

Valid user use small Captcha icons setting values are booleans: setting this value to true will force BotDetect to use small built-in icons, while false will disable automatic switching to small icons depending on image height.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect useSmallIcons="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.UseSmallIcons = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "UseSmallIcons": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" use-small-icons="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" UseSmallIcons="false" 

Remarks

This setting only applies to default BotDetect icons, and should not be used in combination with user-defined icons.

Use Horizontal CAPTCHA Icons

Description

BotDetect displays the Captcha sound and reload icon one below the other by default, and switches to displaying them one beside the other when Captcha images are small enough. This setting allows you to control which BotDetect icon layout will be used.

Default

The default value is true when the Captcha image height is <40px, and false otherwise.

Valid User Setting Values

Valid user use horizontal Captcha icons setting values are booleans: setting this value to true will force BotDetect to use a horizontal icon layout, while false will disable automatic switching to horizontal icons depending on image height.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect useHorizontalIcons="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.UseHorizontalIcons = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "UseHorizontalIcons": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" use-horizontal-icons="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" UseHorizontalIcons="false" 

Remarks

This setting only applies to default BotDetect icons, and should not be used in combination with user-defined icons.

CAPTCHA Sound Icon URL

Description

Url of the optional custom Captcha sound icon that will be used instead of the default one.

Default

The default value is "BotDetect.ashx?get=sound-icon".

Valid User Setting Values

Valid user Captcha sound icon setting values are absolute or relative Urls. When specifying a custom Captcha sound icon, you should make sure its filename includes "icon", and also provide a disabled variation of the icon that will be shown during sound playback (to prevent the user from clicking the icon multiple times). The disabled sound icon variant should be the same size and have a filename based on the active one ("icon" replaced with "disabled-icon").

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundIconUrl="~/custom-sound-icon.gif"" 
or
<botDetect soundIconUrl="http://absoluteurl.com/custom-sound-icon.gif" 
or
<botDetect soundIconUrl="../../images/custom-sound-icon.gif" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundIconUrl = "~/custom-sound-icon.gif"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundIconUrl": "~/custom-sound-icon.gif"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-icon-url="~/custom-sound-icon.gif"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    SoundIconUrl="~/custom-sound-icon.gif" 

CAPTCHA Reload Icon URL

Description

Url of the optional custom Captcha reload icon that will be used instead of the default one.

Default

The default value is "BotDetect.ashx?get=reload-icon".

Valid User Setting Values

Valid user Captcha reload icon setting values are absolute or relative Urls. When specifying a custom Captcha reload icon, you should make sure its filename includes "icon", and also provide a disabled variation of the icon that will be shown while the browser is waiting to fetch a new Captcha challenge from the server (to prevent the user from clicking the icon multiple times). The disabled reload icon variant should be the same size and have a filename based on the active one ("icon" replaced with "disabled-icon").

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect reloadIconUrl="~/custom-reload-icon.gif"" 
or
<botDetect reloadIconUrl="http://absoluteurl.com/custom-reload-icon.gif" 
or
<botDetect reloadIconUrl="../../images/custom-reload-icon.gif" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.ReloadIconUrl = "~/custom-reload-icon.gif"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ReloadIconUrl": "~/custom-reload-icon.gif"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" reload-icon-url="~/custom-reload-icon.gif"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    ReloadIconUrl="~/custom-reload-icon.gif" 

CAPTCHA Icons Div Width

Description

Custom width of the Captcha icons <div> element.

Default

The default value depends on Captcha image height, since BotDetect will automatically determine default icon size and position to match it.

Valid User Setting Values

Valid user Captcha icons div width setting values are positive integers.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect iconsDivWidth="25" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.IconsDivWidth = 25; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "IconsDivWidth": 25
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" icons-div-width="25"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" IconsDivWidth="25" 

Remarks

If your custom Captcha icons are not of the same size as the default BotDetect ones (22x22 px), the UseHorizontalIcons setting won't be able to control the icon layout correctly. You can control whether your custom icons will be displayed one beneath the other or one beside the other by setting an appropriate icons div width: setting it to at least twice the icon width + 8px of padding will result in horizontal icon layout, while smaller values will result in vertical icon layout.

Description

Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users.

Default

The default value is true.

Valid User Setting Values

Valid user help link enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect helpLinkEnabled="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.HelpLinkEnabled = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HelpLinkEnabled": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" help-link-enabled="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" HelpLinkEnabled="false" 

Remarks

This setting is only supported in paid version of BotDetect.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

Description

How will the Captcha help link be displayed.

Default

The default value is Text.

Valid User Setting Values

Valid user Captcha help link mode setting values are members of the BotDetect HelpLinkMode enumeration ("Image" or "Text").

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect helpLinkMode="image" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.HelpLinkMode = HelpLinkMode.Image; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HelpLinkMode": "Image"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" help-link-mode="Image"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" HelpLinkMode="Image" 

Remarks

When using the Image help link mode, Captcha image is wrapped in a link, and clicking it opens the help page in a new browser tab. This mode takes less space, but can lead to accidental clicks (particularly by mobile visitors).

When using the Text help link mode, Captcha image height is automatically reduced by 10 px and a text link to the Captcha help page is inserted below it. If this makes the Captcha images less readable, you can compensate by increasing the Captcha image height.

Since this setting affects Captcha challenge (image or sound) generation in Http requests separate from form execution, it needs to be saved in Session state when set through Captcha object instance properties in form source, consuming server resources and reverting to default when the Session expires. It is recommended to set it through the application configuration file, or user code executing for each Captcha challenge generation Http request instead.

CAPTCHA TabIndex

Description

Starting tabindex for the Captcha container Html markup elements.

Default

The default value is empty (Captcha elements won't have an explicit tabindex set).

Valid User Setting Values

Valid user Captcha tabindex setting values are integers, and -1 is a special value that will disable tabbing over Captcha elements in most browsers.

Example Code

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.TabIndex = 10; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "TabIndex": 10
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" tab-index="10"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" TabIndex="10" 

Remarks

There are three keyboard-selectable Captcha markup elements: the Captcha help link, the Captcha sound icon and the Captcha reload icon. Depending on your settings (whether the Captcha help link is enabled, are Captcha sounds enabled, is Captcha reloading enabled), the next available tabindex on the page can be from 0 to 3 greater than this value.

Since tabindex values depend on the particular form where the Captcha challenge is placed, this BotDetect setting can not be set through application config files, but only in form source.

Add CAPTCHA CSS Include

Description

Should the BotDetect layout stylesheet be automatically added to page <head> if possible.

Default

The default value is true.

Valid User Setting Values

Valid user add Captcha CSS include setting values are booleans.

Example Code

WebFormsCaptcha object instance property:

ExampleCaptcha.AddCssInclude = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AddCssInclude": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" add-css-include="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AddCssInclude="false" 

Remarks

This setting is specific to ASP.NET WebForms, and doesn't apply for ASP.NET MVC or ASP.NET Web Pages Captcha integrations.

If the current ASP.NET WebForm contains a <head runat="server" declaration, the BotDetect WebFormsCaptcha control will attempt to automatically include the BotDetect layout stylesheet within it. If this attempt fails, the WebFormsCaptcha custom web control will fall back to including the BotDetect stylesheet within the generated Captcha container markup – resulting in invalid markup (since stylesheets shouldn't be included within Html <body> tags), but perserving Captcha layout in most browsers.

If you want to add the BotDetect layout stylesheet to form <head> yourself, you can turn off automatic inclusion during control initialization.

If you have multiple Captcha controls per WebForm and only want the first one to add the stylesheet, you can set AddCssInclude to false for all control instances except the first.

CAPTCHA Additional CSS Classes

Description

User-defined CSS classes that will be added to the BotDetect Captcha container <div>.

Default

The default value is empty.

Valid User Setting Values

Valid user additional CSS classes setting values are strings containing desired class names in standard space-delimited CSS class format. CSS style declarations for these custom classes must be defined in a user stylesheet added to the page.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect additionalCssClasses="class1 class2 class3" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AdditionalCssClasses = "class1 class2 class3"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AdditionalCssClasses": "class1 class2 class3"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" additional-css-classes="class1 class2 class3"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    AdditionalCssClasses="class1 class2 class3" 

CAPTCHA Additional Inline CSS

Description

User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container <div>.

Default

The default value is empty.

Valid User Setting Values

Valid user additional CSS style setting values are strings containing desired CSS style declarations in standard semicolon-delimited CSS style format.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect additionalInlineCss="border: 4px solid #fff; background-color: #f8f8f8;" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AdditionalInlineCss = "border: 4px solid #fff; background-color: #f8f8f8;"; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AdditionalInlineCss": "border: 4px solid #fff; background-color: #f8f8f8;"
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" additional-inline-css="border: 4px solid #fff; background-color: #f8f8f8;"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    AdditionalInlineCss="border: 4px solid #fff; background-color: #f8f8f8;" 

Add CAPTCHA Script Include

Description

Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup.

Default

The default value is true.

Valid User Setting Values

Valid user add script include setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect addScriptInclude="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AddScriptInclude = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AddScriptInclude": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" add-script-include="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AddScriptInclude="false" 

Remarks

This setting will usually only be set to false if you have multiple Captcha instances on the same form and only want the first one's markup to include the required BotDetect client-side code. Another possible use is when you manually add the necessary <script> include to page <head>, possibly combined with other JavaScript code and minified to reduce the number of Http requests made by the page.

CAPTCHA Auto Uppercase Input

Description

Should user Captcha code input be automatically uppercased on the fly.

Default

The default value is true.

Valid User Setting Values

Valid user auto uppercase input setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect autoUppercaseInput="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AutoUppercaseInput = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AutoUppercaseInput": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" auto-uppercase-input="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AutoUppercaseInput="false" 

Remarks

Since Captcha validation is not and should not be case-sensitive (it would hinder human visitors more than bots, and how would case differences be communicated through audio Captcha in all supported pronunciation languages?), automatically uppercasing user input is a small usability improvement that helps communicate the case-insensitivity of the Captcha challenge to users.

CAPTCHA Auto Focus Input

Description

Should the Captcha code input textbox automatically 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.

Default

The default value is true.

Valid User Setting Values

Valid user auto focus input setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect autoFocusInput="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AutoFocusInput = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AutoFocusInput": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" auto-focus-input="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AutoFocusInput="false" 

Remarks

Automatic input element focusing is not triggered by auto-reloading of expired Captcha challenges, since the user might be filling out another field on the form when the auto-reload starts and shouldn't be distracted.

CAPTCHA Auto Clear Input

Description

Should the Captcha user input textbox automatically be cleared on all reload icon clicks and auto-reloads of expired Captcha codes.

Default

The default value is true.

Valid User Setting Values

Valid user auto clear input setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect autoClearInput="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AutoClearInput = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AutoClearInput": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" auto-clear-input="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AutoClearInput="false" 

Remarks

Automatic input clearing is a small usability improvement: since any previous user input will be invalidated by Captcha reloading, it helps so users don't have to delete the previous input themselves.

Auto Reload Expired Captchas

Description

Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the Captcha code timeout property).

Default

The default value is true.

Valid User Setting Values

Valid user auto reload expired Captchas setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect autoReloadExpiredCaptchas="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AutoReloadExpiredCaptchas = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AutoReloadExpiredCaptchas": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" auto-reload-expired-captchas="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    AutoReloadExpiredCaptchas="false" 

Remarks

Automatic reloading of expired Captcha codes allows you to have a short Captcha code timeout (e.g. 2 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).

CAPTCHA Auto Reload Timeout

Description

Time period in seconds after which automatic reloading of expired Captcha challenges will cease.

Default

The default value is 7200 seconds (2 hours).

Valid User Setting Values

Valid user auto reload timeout setting values are positive integers.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect autoReloadTimeout="3600" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.AutoReloadTimeout = 3600; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "AutoReloadTimeout": 3600
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" auto-reload-timeout="3600"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" AutoReloadTimeout="3600" 

Remarks

This timeout prevents indefinite extension of the visitor Session, when the user leaves the form open in a background browser tab over the weekend for example.

CAPTCHA Sound Start Delay

Description

Starting delay (in milliseconds) of Captcha audio JavaScript playback.

Default

The default value is 0 (no delay).

Valid User Setting Values

Valid user Captcha sound start delay setting values are positive integers.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect soundStartDelay="1000" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.SoundStartDelay = 1000; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SoundStartDelay": 1000
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" sound-start-delay="1000"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" SoundStartDelay="1000" 

Remarks

An initial delay before browser sound playback can be useful for improving usability of the Captcha audio for blind people using JAWS or similar screen readers. Such assistive technology will read the label associated with the Captcha code textbox and start sound playback simultaneously when the sound icon is activated (since Captcha sound playing automatically focuses the Captcha code textbox by default). 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.

CAPTCHA Remote Scripts Enabled

Description

Should BotDetect also add 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).

Default

The default value is true.

Valid User Setting Values

Valid user remote script enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect remoteScriptEnabled="false" 

Captcha / MvcCaptcha / WebFormsCaptcha object instance property:

ExampleCaptcha.RemoteScriptEnabled = false; 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "RemoteScriptEnabled": false
  }
}

.NET Core Captcha Tag page source:

<captcha id="ExampleCaptcha" remote-script-enabled="false"

ASPX page source:

<BotDetect:WebFormsCaptcha runat="server" ID="ExampleCaptcha" 
    RemoteScriptEnabled="false" 

Remarks

This setting is only supported in paid version of BotDetect.

CAPTCHA HttpHandler Request Path

Description

Path of the BotDetect ASP.NET HttpHandler used for processing Captcha image, sound and Ajax validation requests, as well as accessing all BotDetect public resources (Captcha icons, layout stylesheet, client-script include).

Default

The default value is "BotDetectCaptcha.ashx".

Valid User Setting Values

Valid user Captcha HttpHandler request path setting values are path (filename + extension) strings, which must also be used in application registration of the BotDetect HttpHandler (type="BotDetect.Web.CaptchaHandler, BotDetect").

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect httpHandlerRequestPath="CaptchaCustomPath.ashx" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HttpHandlerRequestPath": "CaptchaCustomPath.ashx"
  }
}

Remarks

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 ASP.NET runtime. For example, you can use the ".jpg" extension only if you re-map ".jpg" requests to be handled by ASP.NET in your application's virtual folder, instead of the default IIS file system mapping for ".jpg" files.

CAPTCHA HttpHandler Troubleshooting Enabled

Description

Should Captcha HttpHandler diagnostics be run.

Default

The default value is false.

Valid User Setting Values

Valid user Captcha HttpHandler troubleshooting enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect httpHandlerTroubleshootingEnabled="true" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "HttpHandlerTroubleshootingEnabled": true
  }
}

Remarks

HttpHandler troubleshooting might be useful while developing your BotDetect-protected form, but should be turned off for production deployments after you ensure the Captcha challenges are working properly.

CAPTCHA Request Filter Enabled

Description

Should the custom Captcha Http request validator be run.

Default

The default value is true.

Valid User Setting Values

Valid user Captcha request filter enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect requestFilterEnabled="false" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "RequestFilterEnabled": false
  }
}

Remarks

The custom Captcha Http request validator counts the number of repeated Captcha HttpHandler requests with the exact same query string, and stops generating Captcha challenges if a certain repetition threshold is exceeded. Human users using regular browsers will mostly request each Captcha challenge with a unique query string (a small number of repeated requests is possible depending on the browser), while simple scraping bots will often repeat the same request a large number of times, wasting server resources.

Current qequest count is stored in ASP.NET HttpRuntime.Cache, with sliding expiration using the same timeout as the current ASP.NET Session timeout (which controls most aspects of Captcha functionality anyway). When the allowed repeated request count is exceeded, the Captcha HttpHandler will just send a 400 Bad Request response to the client instead of generating a new Captcha challenge for a bot.

This kind of Http request validation is a simple optional Captcha workflow optimization meant primarily to conserve server CPU resources, and can be turned off without compromising Captcha security if you want to conserve server memory (used for ASP.NET HttpRuntime.Cache storage) instead.

CAPTCHA Request Filter Repeated Requests Allowed

Description

How many repeated Captcha HttpHandler requests using the exact same query string will be allowed in a short time period.

Default

The default value is 5.

Valid User Setting Values

Valid user Captcha request filter repeated requests allowed setting values are positive integers between 1 and 100.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect requestFilterRepeatedRequestsAllowed="10" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "RequestFilterRepeatedRequestsAllowed": 10
  }
}

Remarks

You will typically only increase this value if the Captcha request filter is for some reason causing issues with legitimate user behavior in your application.

CAPTCHA Session Troubleshooting Enabled

Description

Should Captcha Session state persistence diagnostics be run.

Default

The default value is true.

Valid User Setting Values

Valid user Captcha Session troubleshooting setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect sessionTroubleshootingEnabled="false" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "SessionTroubleshootingEnabled": false
  }
}

Remarks

For each incoming request, BotDetect will attempt to detect and report a number of possible ASP.NET Session-related issues: is the ASP.NET Session HttpModule not running at all, is Session state (and more particularly, Captcha persistence) empty when it should already contain some values, is a new ASP.NET Session started on a POST request that attempts to validate user Captcha input (which requires the Captcha code previously stored in Session state) etc.

CAPTCHA Session ID Encryption Password

Description

Password used to generate the encryption key used for obscuring SessionID values required for the BotDetect CustomSessionIDManager to work around cookie limitations of sound playback in certain browsers.

Default

The default value depends on the ASP.NET application context.

Valid User Setting Values

Valid user Captcha encryption setting values are arbitrary strings.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect encryptionPassword="SecretEncryptionPassword" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "EncryptionPassword": "SecretEncryptionPassword"
  }
}

Remarks

The ASP.NET SessionID should never be passed in plaintext query string, to avoid Session hijacking or spoofing attacks. If you're using the BotDetect CustomSessionIDManager as a workaround for Captcha sound playback issues in certain browsers, it is recommended to specify your own unique SessionID encryption password. Please note that this password is not used for any other purpose beside encrypting SessionID values embedded in Captcha sound Urls (so the correct ASP.NET Session can be identified even when the client loses the SessionID cookie on sound requests), and does not affect Captcha security in any manner.

CAPTCHA Logging Provider

Description

Fully-qualified name of a .NET class implementing the BotDetect.Logging.ILoggingProvider interface, loaded by the current ASP.NET application and used to process all BotDetect logging calls.

Default

The default value is "BotDetect.Logging.NullLoggingProvider, BotDetect".

Valid User Setting Values

Valid user Captcha logging provider setting values are fully qualified names of .NET classes available in the current ASP.NET application and implementing the BotDetect.Logging.ILoggingProvider interface.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect loggingProvider="BotDetect.Logging.NullLoggingProvider, BotDetect" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "LoggingProvider": "BotDetect.Logging.NullLoggingProvider, BotDetect"
  }
}

Remarks

The default BotDetect.Logging.NullLoggingProvider will ignore all Captcha log statements. If you want to use log4net to log Captcha errors and a detailed execution trace, switch to "BotDetect.Logging.Log4NetLoggingProvider, BotDetect.Troubleshooting" (BotDetect.Troubleshooting.dll and a redistribution of log4net.dll is included in the BotDetect ASP.NET Captcha installation). If you want to send the Captcha log to a different logging provider, you will have to find or implement a class that uses the desired back-end to implement the BotDetect.Logging.ILoggingProvider interface.

Please note that BotDetect uses reflection to instantiate custom logging classes, so such Captcha logging will only work in applications with the required execution permissions.

CAPTCHA Error Logging Enabled

Description

Should exceptions originating in BotDetect code be logged to the currently active Captcha logging provider.

Default

The default value is false.

Valid User Setting Values

Valid user Captcha error logging enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect errorLoggingEnabled="true" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "ErrorLoggingEnabled": true
  }
}

CAPTCHA Trace Logging Enabled

Description

Should a detailed trace of the Captcha generation and validation workflow be logged to the currently active Captcha logging provider.

Default

The default value is false.

Valid User Setting Values

Valid user Captcha Trace logging enabled setting values are booleans.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect traceLoggingEnabled="true" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "TraceLoggingEnabled": true
  }
}

CAPTCHA Trace Logging Event Filter

Description

Filter which Captcha events will be included in the BotDetect trace log.

Default

The default value is ".*".

Valid User Setting Values

Valid user Captcha trace event filter setting values are strings with regular expressions that will be matched against BotDetect event names. Event names used by BotDetect code are: InitializedWebCaptcha, GeneratingCaptchaCode, GeneratedCaptchaCode, GeneratingCaptchaImage, GeneratedCaptchaImage, GeneratingCaptchaSound, GeneratedCaptchaSound, ValidatingUserInput, ValidatedUserInput, Warning. This makes it easy to construct a regex expression that will filter and log only the BotDetect events you are interested in.

Example Code

Legacy .NET application web.config configuration file setting:

<botDetect traceLoggingEventFilter="(Initialized)|(Generated)" 
or
<botDetect traceLoggingEventFilter="CaptchaImage" 
or
<botDetect traceLoggingEventFilter="Warning" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "TraceLoggingEventFilter": "CaptchaImage"
  }
}

FIPS Compliance Enabled

Description

Is FIPS Compliance enabled.

Default

The default value is false.

Valid User Setting Values

Valid user FIPS Compliance enabled setting values are booleans.

Example Code

<botDetect fipsComplianceEnabled="true" 

.NET Core application appsettings.json configuration file setting:

{
  "BotDetect": {
    "FIPSComplianceEnabled": true
  }
}

Remarks

Captcha FIPS Compliance can be enabled entirely by setting this property to true.

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

Convert BotDetect v3 ASP.NET CAPTCHA Config Section into BotDetct v4 CAPTCHA Config Format

Paste the BotDetect v3 configuration section (including the starting <botDetect> and ending </botDetect> tags) here and click Convert.