Captcha Library

The captcha library provides a means to generate two flavors of captchas. In it's first form the library enables you to display a barrier-free captcha in the form of digits composed of none breaking spaces. In it's second form the library generates a random math problem by using either 4 or 2 randomly chosen arithmetic operations.

Here is an example of the none breaking spaces captcha:

Generated number:

1369

Hash generated by combining the captcha number with your secret key which is located in your application/config/config.lc file:

9e883aabcdd63ba74d48eabdae0b2a28

Displayed captcha:

                              
                              
                              
                              
                              

 

Following an example of a random math problem captcha:

Math problem result:

8

Hash generated by combining the result number with your secret key which is located in your application/config/config.lc file:

404f1b3e6a17f39520f7dd31d229e0b2

Math problem:

32 / 4

 

Initializing the Library

Like most other libraries in revIgniter, the Captcha Library is initialized in your controller using the rigLoaderLoadLibrary handler:

rigLoaderLoadLibrary "Captcha"

Example (none breaking spaces digits)

Here is a simple example showing how to create a captcha (composed of none breaking spaces) in one of your controller handlers:

rigLoaderLoadLibrary "Captcha" 
 
# GET CAPTCHA, THE HTML CODE WHICH DISPLAYS THE CAPTCHA DIGITS 
put rigCaptcha() into gData["captcha"] 
 
# GET CAPTCHA CSS 
put rigCaptchaStyle() into gData["captchaStyle"]

Note: Place the gData["captchaStyle"] variable to be merged in the header of your view file. This variable holds the style data for your captcha.

In order to prevent automated software from posting to your site you need to store a hash of the captcha digits which is built from the captcha number and a key stored in your application/config/config.lc file, in a hidden field. Then you have to compare the posted data of the hidden field with a hash of the posted number. To retrieve the hash of the displayed captcha your code would look like this:

rigLoaderLoadLibrary "Captcha" 
 
# GET CAPTCHA, THE HTML CODE WHICH DISPLAYS THE CAPTCHA DIGITS 
put rigCaptcha() into gData["captcha"] 
 
# GET CAPTCHA CSS 
put rigCaptchaStyle() into gData["captchaStyle"] 
 
# GET CAPTCHA HASH 
put rigGetCaptchaHash() into gData["captchaHash"]

Here is an example for captcha user input validation:

if rigValidCaptchaUserInput(rigVarPost("inputField"), rigVarPost("hiddenHashField")) is TRUE then 
	get rigLoadView("formSuccess") 
end if

Where rigVarPost("inputField") is the posted captcha user input and rigVarPost("hiddenHashField") is the captcha hash.

Note: To re-populate the form fields on invalid user input for the captcha, use a hidden field with the default value set to empty. Set a callback handler in the validation rules for this field, for more info please see Form Validation Library.
Do the captcha validation and on failure set the value of $_POST["nameOfYourHiddenField"] to anything besides empty. This value will be sent as parameter to your callback handler. In your callback handler check this parameter, and if it is not empty return FALSE, otherwise TRUE. Re-populating of the form fields will then be done by the Form Validation Library.

Here is an example:

# VALIDATION RULES (in your validation config file in system/application/config/validation.lc) 
 
put "hiddenMonitorField" into sValidationConf["idOfYourForm"][1]["field"] 
put "Enter captcha number here" into sValidationConf["idOfYourForm"][1]["label"] 
put "callback_captchaFailed" into sValidationConf["idOfYourForm"][1]["rules"] 
 
put "inputField" into sValidationConf["idOfYourForm"][2]["field"] 
put "Enter captcha number here" into sValidationConf["idOfYourForm"][2]["label"] 
put "trim|requiredR|maxLengthR[4]|integerR" into sValidationConf["idOfYourForm"][2]["rules"] 
 
# CAPTCHA VALIDATION 
 
put FALSE into tCaptchaValid 
if $_POST is an array then 
	if rigVarPOST("inputField") is not FALSE then 
		if rigValidCaptchaUserInput(rigVarPOST("inputField"), rigVarPOST("hiddenHashField")) is TRUE then 
			put TRUE into tCaptchaValid 
		else 
			# SET THE INPUT OF THE HIDDEN FIELD TO TRUE, THIS WILL BE THE PARAMETER FOR THE CALLBACK HANDLER 
			# THE PAGE WILL THEN BE SHOWN AGAIN WITH REPOPULATED FIELDS 
			put "true" into $_POST["hiddenMonitorField"] 
		end if 
	end if 
end if 
 
# CALLBACK HANDLER 
 
command captchaFailed pStr 
	# pStr IS THE HIDDEN FIELD INPUT SET TO TRUE AS SHOWN ABOVE IF USER INPUT FOR CAPTCHA WAS WRONG 
	if pStr = "true" then 
		# SHOW CAPTCHA ERROR 
		put "Wrong input in field %s." into tCaptchaError 
		rigSetMessage "captchaFailed", tCaptchaError 
		# RETURN FALSE, SO THAT THE PAGE IS SHOWN AGAIN AND THE FIELDS ARE REPOPULATED 
		return FALSE 
	else 
		return TRUE 
	end if 
end captchaFailed

Example (random math problem)

Here is a simple example showing how to create a captcha (displaying a math problem) in one of your controller handlers:

rigLoaderLoadLibrary "Captcha" 
 
# GET CAPTCHA MATH PROBLEM 
put rigCaptchaMathProblem() into gData["captcha"] 
 
#GET CAPTCHA HASH 
put rigGetCaptchaHash() into gData["captchaHash"]

In order to prevent automated software from posting to your site you need to store a hash of the math problem result which is built from the result number and a key stored in your application/config/config.lc file, in a hidden field. Then you have to compare the posted data of the hidden field with a hash of the posted number.

Note: The methods for input validation comply with those shown above.

Captcha Configuraton

There are 4 different preferences available in your application/config/config.lc file. You can change them in the config file or you can set them manually as described below.

Explanation of Values:

Preferences are set by passing an array of preference values to the captcha rigInitCaptcha handler. Here is an example of how you might set preferences:

rigLoaderLoadLibrary "Captcha" 
 
put 6 into tConfig["captchaLength"] 
put "#FFFFFF" into tConfig["captchaBckgndColor"] 
put "#646464" into tConfig["captchaColor"] 
 
rigInitCaptcha tConfig

Note: To change your secret key change the corresponding entry in the config file. Don't set it manually like other preferences shown above.

Captcha Handler Reference

rigCaptcha()

Call this function first in case you want to get a none breaking spaces captcha:

put rigCaptcha() into gData["captcha"]

rigCaptchaMathProblem(pNumberOfOperators)

Call this function first in case you want to get a random math problem captcha:

put rigCaptchaMathProblem() into gData["captcha"]

The parameter defines the number of operators used to generate a math problem. Leave empty to set the number of operators to four (+,-,/,*), enter "2" to set the number of operators to two (+,-).

rigCaptchaStyle(pNonce)

Get captcha style tags to be placed in the header of the view file:

put rigCaptchaStyle() into gData["captchaStyle"]

Use the optional parameter to add a nonce (as used by Content Security Policy headers) to the style tags. Example:

put rigNonce() into tNonce
put "'nonce-" & tNonce & "'" into tSrcNonce
put rigCaptchaStyle(tNonce) into gData["captchaStyle"]

# THEN GENERATE A Content-Security-Policy META TAG TO BE USED IN THE HEADER
rigLoadHelper "html"
put "Content-Security-Policy" into tCspMetaA["name"]
put "style-src 'self'" && tSrcNonce into tCspMetaA["content"]
put "equiv" into tCspMetaA["type"]
put rigHtmlMeta(tCspMetaA) into gData["cspTag"]

rigGetCaptchaHash()

Get hash from captcha number and a key. You may store this string in a hidden form field:

put rigGetCaptchaHash() into gData["captchaHash"]

rigGetCaptchaNum()

Get number the captcha is built with / get the result of a math problem:

put rigGetCaptchaNum() into gData["captchaNum"]

rigValidCaptchaUserInput(pCaptchaInput, pHiddenFieldValue)

Validate captcha user input. The first parameter is the posted captcha user input and the second is the captcha hash retrieved from an hidden field. The function returns TRUE or FALSE.

if rigValidCaptchaUserInput(tInput, tHiddenField) is TRUE then 
	-- your code here 
end if

rigInitCaptcha pConfigArray

Used to set initial values whenever the library is loaded. The parameter is an array of captcha settings described above:

rigInitCaptcha tConfig

Note: These captcha solutions are far from being 100% secure. So, if security is crucial you should implement additional spam stoppers for a higher degree of security.