Class TCaptcha

Description

TCaptcha class.

Notice: while this class is easy to use and implement, it does not provide full security. In fact, it's easy to bypass the checks reusing old, already-validated tokens (reply attack). A better alternative is provided by TReCaptcha.

TCaptcha displays a CAPTCHA (a token displayed as an image) that can be used to determine if the input is entered by a real user instead of some program.

Unlike other CAPTCHA scripts, TCaptcha does not need session or cookie.

The token (a string consisting of alphanumeric characters) displayed is automatically generated and can be configured in several ways. To specify the length of characters in the token, set MinTokenLength and MaxTokenLength. To use case-insensitive comparison and generate upper-case-only token, set CaseSensitive to false. Advanced users can try to set TokenAlphabet, which specifies what characters can appear in tokens.

The validation of the token is related with two properties: TestLimit and TokenExpiry. The former specifies how many times a token can be tested with on the server side, and the latter says when a generated token will expire.

To specify the appearance of the generated token image, set TokenImageTheme to be an integer between 0 and 63. And to adjust the generated image size, set TokenFontSize (you may also set TWebControl::setWidth, but the scaled image may not look good.) By setting ChangingTokenBackground to true, the image background of the token will be variating even though the token is the same during postbacks.

Upon postback, user input can be validated by calling validate(). The TCaptchaValidator control can also be used to do validation, which provides client-side validation besides the server-side validation. By default, the token will remain the same during multiple postbacks. A new one can be generated by calling regenerateToken() manually.

The following template shows a typical use of TCaptcha control:

  1.  <com:TCaptcha ID="Captcha" />
  2.  <com:TTextBox ID="Input" />
  3.  <com:TCaptchaValidator CaptchaControl="Captcha"
  4.                         ControlToValidate="Input"
  5.                         ErrorMessage="You are challenged!" />

  • author: Qiang Xue <qiang.xue@gmail.com>
  • version: $Id: TCaptcha.php 3044 2011-10-02 21:13:53Z ctrlaltca@gmail.com $
  • since: 3.1.1

Located in /Web/UI/WebControls/TCaptcha.php (line 64)

TComponent
   |
   --TApplicationComponent
      |
      --TControl
         |
         --TWebControl
            |
            --TImage
               |
               --TCaptcha
Class Constant Summary
Method Summary
static boolean checkRequirements ()
string generateRandomKey ()
string generateToken (string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength,  $caseSensitive)
boolean getCaseSensitive ()
void getFontFile ()
boolean getIsTokenExpired ()
integer getMaxTokenLength ()
integer getMinTokenLength ()
string getPrivateKey ()
string getPublicKey ()
integer getTestLimit ()
string getToken ()
string getTokenAlphabet ()
integer getTokenExpiry ()
integer getTokenFontSize ()
integer getTokenImageTheme ()
integer getTokenLength ()
string hash2string (string $hex, [string $alphabet = ''])
void onPreRender (mixed $param)
void regenerateToken ()
void setCaseSensitive (boolean $value)
void setChangingTokenBackground (boolean $value)
void setMaxTokenLength (integer $value)
void setMinTokenLength (integer $value)
void setPublicKey (string $value)
void setTestLimit (integer $value)
void setTokenAlphabet (string $value)
void setTokenExpiry (integer $value)
void setTokenFontSize (integer $value)
void setTokenImageTheme (integer $value)
boolean validate (string $input)
Variables

Inherited Variables

Inherited from TWebControl

TWebControl::$_decorator
Methods
static method checkRequirements (line 490)

Checks the requirements needed for generating CAPTCHA images.

TCaptach requires GD2 with TrueType font support and PNG image support.

  • return: whether the requirements are satisfied.
  • access: public
static boolean checkRequirements ()
generatePrivateKeyFile (line 421)

Generates a file with a randomly generated private key.

  • return: the path of the file keeping the private key
  • access: protected
string generatePrivateKeyFile ()
generateRandomKey (line 441)
  • return: a randomly generated key
  • access: protected
string generateRandomKey ()
generateToken (line 454)

Generates the token.

  • return: the token generated.
  • access: protected
string generateToken (string $publicKey, string $privateKey, integer $alphabet, boolean $tokenLength,  $caseSensitive)
  • string $publicKey: public key
  • string $privateKey: private key
  • integer $alphabet: the length of the token
  • boolean $tokenLength: whether the token is case sensitive
  • $caseSensitive
getCaptchaScriptFile (line 407)
  • return: the file path of the PHP script generating the token image
  • access: protected
string getCaptchaScriptFile ()
getCaseSensitive (line 167)
  • return: whether the token should be treated as case-sensitive. Defaults to true.
  • access: public
boolean getCaseSensitive ()
getChangingTokenBackground (line 217)
  • return: whether the background of the token image should be variated during postbacks. Defaults to false.
  • access: public
boolean getChangingTokenBackground ()
getFontFile (line 412)
  • access: protected
void getFontFile ()
getIsTokenExpired (line 249)
  • return: whether the currently generated token has expired.
  • access: public
boolean getIsTokenExpired ()
getMaxTokenLength (line 147)
  • return: the maximum length of the token. Defaults to 6.
  • access: public
integer getMaxTokenLength ()
getMinTokenLength (line 127)
  • return: the minimum length of the token. Defaults to 4.
  • access: public
integer getMinTokenLength ()
getPrivateKey (line 309)
  • return: the private key used for generating the token. This is randomly generated and kept in a file for persistency.
  • access: public
string getPrivateKey ()
getPublicKey (line 260)
  • return: the public key used for generating the token. A random one will be generated and returned if this is not set.
  • access: public
string getPublicKey ()
getTestLimit (line 233)
  • return: how many times a generated token can be tested. Defaults to 5.
  • access: public
integer getTestLimit ()
getToken (line 281)
  • return: the token that will be displayed
  • access: public
string getToken ()
getTokenAlphabet (line 183)
  • return: the characters that may appear in the token. Defaults to '234578adefhijmnrtABDEFGHJLMNRT'.
  • access: public
string getTokenAlphabet ()
getTokenExpiry (line 201)
  • return: the number of seconds that a generated token will remain valid. Defaults to 600 seconds (10 minutes).
  • access: public
integer getTokenExpiry ()
getTokenFontSize (line 104)
  • return: the font size used for displaying the token in an image. Defaults to 30.
  • access: public
integer getTokenFontSize ()
getTokenImageOptions (line 383)
  • return: the options to be passed to the token image generator
  • access: protected
string getTokenImageOptions ()
getTokenImageTheme (line 74)
  • return: the theme of the token image. Defaults to 0.
  • access: public
integer getTokenImageTheme ()
getTokenLength (line 289)
  • return: the length of the token to be generated.
  • access: protected
integer getTokenLength ()
hash2string (line 466)

Converts a hash string into a string with characters consisting of alphanumeric characters.

  • return: the converted string
  • access: protected
string hash2string (string $hex, [string $alphabet = ''])
  • string $hex: the hexadecimal representation of the hash string
  • string $alphabet: the alphabet used to represent the converted string. If empty, it means '234578adefhijmnrtwyABDEFGHIJLMNQRTWY', which excludes those confusing characters.
onPreRender (line 363)

Configures the image URL that shows the token.

  • access: public
void onPreRender (mixed $param)
  • mixed $param: event parameter

Redefinition of:
TWebControl::onPreRender()
If your subclass overrides the onPreRender method be sure to call this method through parent::onPreRender($param); so your sub-class can be decorated, among other things.
regenerateToken (line 350)

Regenerates the token to be displayed.

By default, a token, once generated, will remain the same during the following page postbacks. Calling this method will generate a new token.

  • access: public
void regenerateToken ()
setCaseSensitive (line 175)
  • access: public
void setCaseSensitive (boolean $value)
  • boolean $value: whether the token should be treated as case-sensitive. If false, only upper-case letters will appear in the token.
setChangingTokenBackground (line 225)
  • access: public
void setChangingTokenBackground (boolean $value)
  • boolean $value: whether the background of the token image should be variated during postbacks.
setMaxTokenLength (line 155)
  • access: public
void setMaxTokenLength (integer $value)
  • integer $value: the maximum length of the token. It must be between 2 and 40.
setMinTokenLength (line 135)
  • access: public
void setMinTokenLength (integer $value)
  • integer $value: the minimum length of the token. It must be between 2 and 40.
setPublicKey (line 273)
  • access: public
void setPublicKey (string $value)
  • string $value: the public key used for generating the token. A random one will be generated if this is not set.
setTestLimit (line 241)
  • access: public
void setTestLimit (integer $value)
  • integer $value: how many times a generated token can be tested. For unlimited tests, set it to 0.
setTokenAlphabet (line 191)
  • access: public
void setTokenAlphabet (string $value)
  • string $value: the characters that may appear in the token. At least 2 characters must be specified.
setTokenExpiry (line 209)
  • access: public
void setTokenExpiry (integer $value)
  • integer $value: the number of seconds that a generated token will remain valid. A value smaller than 1 means the token will not expire.
setTokenFontSize (line 115)

Sets the font size used for displaying the token in an image.

This property affects the generated token image size. The image width is proportional to this font size.

  • access: public
void setTokenFontSize (integer $value)
  • integer $value: the font size used for displaying the token in an image. It must be an integer between 20 and 100.
setTokenImageTheme (line 92)

Sets the theme of the token image.

You may test each theme to find out the one you like the most. Below is the explanation of the theme value: It is treated as a 5-bit integer. Each bit toggles a specific feature of the image. Bit 0 (the least significant): whether the image is opaque (1) or transparent (0). Bit 1: whether we should add white noise to the image (1) or not (0). Bit 2: whether we should add a grid to the image (1) or not (0). Bit 3: whether we should add some scribbles to the image (1) or not (0). Bit 4: whether the image background should be morphed (1) or not (0). Bit 5: whether the token text should cast a shadow (1) or not (0).

  • access: public
void setTokenImageTheme (integer $value)
  • integer $value: the theme of the token image. It must be an integer between 0 and 63.
validate (line 329)

Validates a user input with the token.

  • return: if the user input is not the same as the token.
  • access: public
boolean validate (string $input)
  • string $input: user input

Inherited Methods

Inherited From TImage

TImage::addAttributesToRender()
TImage::getAlternateText()
TImage::getData()
TImage::getDescriptionUrl()
TImage::getImageAlign()
TImage::getImageUrl()
TImage::getTagName()
TImage::renderContents()
TImage::setAlternateText()
TImage::setData()
TImage::setDescriptionUrl()
TImage::setImageAlign()
TImage::setImageUrl()

Inherited From TWebControl

TWebControl::addAttributesToRender()
TWebControl::clearStyle()
TWebControl::copyBaseAttributes()
TWebControl::createStyle()
TWebControl::getAccessKey()
TWebControl::getBackColor()
TWebControl::getBorderColor()
TWebControl::getBorderStyle()
TWebControl::getBorderWidth()
TWebControl::getCssClass()
TWebControl::getDecorator()
TWebControl::getDisplay()
TWebControl::getEnsureId()
TWebControl::getFont()
TWebControl::getForeColor()
TWebControl::getHasStyle()
TWebControl::getHeight()
TWebControl::getStyle()
TWebControl::getTabIndex()
TWebControl::getTagName()
TWebControl::getToolTip()
TWebControl::getWidth()
TWebControl::onPreRender()
TWebControl::render()
TWebControl::renderBeginTag()
TWebControl::renderContents()
TWebControl::renderEndTag()
TWebControl::setAccessKey()
TWebControl::setBackColor()
TWebControl::setBorderColor()
TWebControl::setBorderStyle()
TWebControl::setBorderWidth()
TWebControl::setCssClass()
TWebControl::setDisplay()
TWebControl::setEnsureId()
TWebControl::setForeColor()
TWebControl::setHeight()
TWebControl::setStyle()
TWebControl::setTabIndex()
TWebControl::setToolTip()
TWebControl::setWidth()

Inherited From TControl

TControl::__construct()
TControl::addedControl()
TControl::addParsedObject()
TControl::addToPostDataLoader()
TControl::applyStyleSheetSkin()
TControl::autoBindProperty()
TControl::autoDataBindProperties()
TControl::bindProperty()
TControl::broadcastEvent()
TControl::bubbleEvent()
TControl::clearChildState()
TControl::clearControlState()
TControl::clearNamingContainer()
TControl::clearViewState()
TControl::convertUniqueIdToClientId()
TControl::createChildControls()
TControl::createControlCollection()
TControl::dataBind()
TControl::dataBindChildren()
TControl::dataBindProperties()
TControl::ensureChildControls()
TControl::findControl()
TControl::findControlsByID()
TControl::findControlsByType()
TControl::focus()
TControl::getAdapter()
TControl::getAllowChildControls()
TControl::getAttribute()
TControl::getAttributes()
TControl::getChildControlsCreated()
TControl::getClientID()
TControl::getControls()
TControl::getControlStage()
TControl::getControlState()
TControl::getCustomData()
TControl::getEnabled()
TControl::getEnableTheming()
TControl::getEnableViewState()
TControl::getHasAdapter()
TControl::getHasAttributes()
TControl::getHasChildInitialized()
TControl::getHasControls()
TControl::getHasInitialized()
TControl::getHasLoaded()
TControl::getHasLoadedPostData()
TControl::getHasPreRendered()
TControl::getID()
TControl::getIsSkinApplied()
TControl::getNamingContainer()
TControl::getPage()
TControl::getParent()
TControl::getRegisteredObject()
TControl::getSkinID()
TControl::getSourceTemplateControl()
TControl::getTemplateControl()
TControl::getUniqueID()
TControl::getViewState()
TControl::getVisible()
TControl::hasAttribute()
TControl::initRecursive()
TControl::isDescendentOf()
TControl::isObjectRegistered()
TControl::loadRecursive()
TControl::loadState()
TControl::loadStateRecursive()
TControl::onDataBinding()
TControl::onInit()
TControl::onLoad()
TControl::onPreRender()
TControl::onUnload()
TControl::preRenderRecursive()
TControl::raiseBubbleEvent()
TControl::registerObject()
TControl::removeAttribute()
TControl::removedControl()
TControl::render()
TControl::renderChildren()
TControl::renderControl()
TControl::saveState()
TControl::saveStateRecursive()
TControl::setAdapter()
TControl::setAttribute()
TControl::setChildControlsCreated()
TControl::setControlStage()
TControl::setControlState()
TControl::setCustomData()
TControl::setEnabled()
TControl::setEnableTheming()
TControl::setEnableViewState()
TControl::setID()
TControl::setPage()
TControl::setSkinID()
TControl::setTemplateControl()
TControl::setViewState()
TControl::setVisible()
TControl::trackViewState()
TControl::traverseChildControls()
TControl::unbindProperty()
TControl::unloadRecursive()
TControl::unregisterObject()
TControl::__get()

Inherited From TApplicationComponent

TApplicationComponent::getApplication()
TApplicationComponent::getRequest()
TApplicationComponent::getResponse()
TApplicationComponent::getService()
TApplicationComponent::getSession()
TApplicationComponent::getUser()
TApplicationComponent::publishAsset()
TApplicationComponent::publishFilePath()

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__call()
TComponent::__get()
TComponent::__set()
TComponent::__sleep()
TComponent::__wakeup()
Class Constants

Documentation generated on Mon, 25 Jun 2012 14:37:29 +0200 by phpDocumentor 1.4.3