BotDetect CAPTCHA PHP FAQ (BotDetect v3.0; deprecated)

At the moment, the BotDetect PHP Captcha library is only developed and tested against newer PHP 5.5.x, 5.4.x, 5.3.x and PHP 5.2.x releases (with 5.2.1 and 5.3.2 being the oldest compatible releases we are aware of).

To check which error causes the issue, right-click on the broken Captcha image and copy its Url (or use View Source and copy the image Url from there). Then open a new browser tab and paste the Captcha image Url to access it directly.

The most common error is

PHP Fatal error: Call to undefined function imagecreatetruecolor()

which is caused by trying to use BotDetect in PHP installations without the GD library. Since BotDetect requires the GD library to generate Captcha images, you can resolve this error by installing it.

BotDetect uses botdetect.php paths to both include the Captcha library and serve Captcha images and sounds. For BotDetect to work properly, you must ensure that botdetect.php requests are not included in Url rewriting or routing of any kind (for example: .htaccess redirects, Url rewriting or routing by your CMS or blog engine). If you need to change the path used by BotDetect, you must also modify the BotDetect HandelrUrl configuration property.

Since BotDetect supports multi-language Captcha generation in a variety of non-Latin character sets, the mbstring module is required for proper Unicode functionality.

At the moment (in the second Alpha release), BotDetect Captcha validation has only been tested to work correctly when using PHP Sessions.

However, if you take a look at the botdetect/CaptchaConfig.php file included in the Captcha library, you can see there are three persistence-related functions defined outside the core library source: LBD_Persistence_Save(), LBD_Persistence_Load(), and LBD_Persistence_Clear().

BotDetect doesn't use PHP sessions directly, but always calls these functions when dealing with persistence - so if you want to customize the storage medium (to, for example, save data to a MySQL database), you can modify these functions to implement alternate data access.

(Please note, botdetect/CaptchaHandler.php does call session_start() in the first line, since it is meant to process direct requests and can't rely on your form code to do so. Depending on your changes, you might want to also comment-out this line and the corresponding session_write_close() calls.)

That's exactly how BotDetect v1.0 used to work, and we abandoned that approach because it was a major security flaw.

Captchas with any kind of client-side persistence can be bypassed easily. For example, if a hashed token of the Captcha code is kept on the client, a simple replay attack can reuse a single correct Captcha code thousands of times. Implementation details vary, but all forms of client-side persistence can be tampered with and attacked by malicious clients.

BotDetect must use server side persistence by design - and we chose that approach because we believe it to be the right way to implement a secure Captcha.

Considering the nature of Captcha data that is persisted, the storage medium should be: per-visitor, server-side, automatically cleared - and Session state is the simplest option that fits those requirements.

If you're interested in changing the underlying persistence medium used by BotDetect, take a look at BotDetect persistence onfiguration options.

You have most likely forgotten to include Captcha validation code in the PHP script that processes your form's submitted data. You can see an example code snippet for Captcha validation in the How To add BotDetect Captcha protection to PHP forms guide.

Also, you might want to take a look at the BotDetect PHP integration samples that come with BotDetect downloads, starting with the PHP basic Captcha integration code sample.

You are right, and this behavior of the Captcha component is by design. Only one validation attempt is allowed per Captcha code for security purposes.

If we allowed multiple retries on solving the same Captcha, it would significantly lower the Captcha security, since bots could just brute-force different code values until they eventually got it right. Also, it would be much easier to write a bot which used OCR techniques to bypass the Captcha: if, for example, it could recognize two out of the five digits in the image, it would just have to brute-force the remaining three.

So a failed validation attempt (whether on the client- or server-side) always invalidates the current Captcha code. Successful server-side validations also remove the code (so we prevent cases where somebody solves just one Captcha and then keeps reusing it for multiple submissions).

Successful client-side validations are the only ones that don't invalidate the current code, so you can also validate the same submitted values on the server-side once all form fields have been filled-out.

So basically, if the Captcha validation attempt wasn't successful, the Captcha image also needs to be reloaded and the previous user input cleared, since the old Captcha code has been invalidated.

If you want to avoid full page submissions, you could take a look at the PHP jQuery Validation Captcha integration and BotDetect PHP built-in Ajax Captcha validation samples coming with the BotDetect download, which use Ajax requests to only submit Captcha validation data to the server and update the client display based on the Captcha validation result.

Pure client-side CAPTCHA validation drawbacks

Pure client-side Captcha validation (without any communication with the server) is not supported by BotDetect, since such a Captcha is trivial to bypass, and doesn't provide any serious protection from bots. For example:

• You want users to post comments only if they have successfully solved the Captcha.
• If the Captcha validation is purely client-side, this means JavaScript code must send the user's comment to the server when the Captcha code is entered correctly.
• So the spammer only needs to solve the Captcha once, and note how you handle the result: e.g. sending a specific POST parameter, or redirecting to a specific page.
• After that, they can simulate the same behavior in their bot and bypass the Captcha completely – by simply faking the POST parameter, or accessing the redirection landing page directly.
• You can back the client-side Captcha validation by also validating the same user input on the server once the page is posted and before recording the user comment.
• But since you are keeping the correct Captcha solution on the client for validation, bots can have easy access to that code and then always solve the Captcha correctly.

The exact details would of course depend on your specific use-case and Captcha integration scenario. But essentially, all client-side code is insecure and can be faked or modified by malicious parties. As a consequence, Captcha codes must only be kept on the server, and all Captcha validation must be performed on the server as well.

Client-side Captcha validation - the solution

You can avoid full page submissions by using Ajax to make asynchronous Captcha validation requests to the server, and processing the result on the client:

• When the Ajax Captcha validation fails, you can show the user a new Captcha image without affecting the rest of the page, thus improving the user experience and overall usability of the page.
• You should always change the Captcha code in such cases, since allowing multiple attempts at solving the same Captcha makes OCR guessing much easier.
• When the Ajax Captcha validation succeeds, you should then submit the page to the server and validate the user Captcha input again.
• Only after successful server-side Captcha validation should you execute the "protected" operation (e.g. record the user comment) on the server.

Users definitely shouldn't have to solve another Captcha if they enter the correct Captcha code, but (for example) username validation fails. The purpose of Captcha is to ensure the user is human, and once they solve it this purpose is fulfilled.

If you have to return them to the form because another field value needs to be corrected, it's best not to show them the Captcha at all.

BotDetect remembers that the user has passed the Captcha test successfully in the IsSolved instance field, and you can only display and validate the Captcha if it hasn't already been solved. See the PHP Form Captcha code sample for a demonstration of this feature.

For security reasons, it is not possible to get the same BotDetect Captcha image on two page loads, nor to use the same code for more than one Captcha image.