accounts.stateless_captcha package

Stateless captcha.

This module provides a captcha that does not require storing anything.

When the user visits a form view for which captcha is required, a new captcha token can be generated using the new() function in this module. The token contains the challenge answer, as well as an expiration. The token is encrypted using a server-side secret and the IP address of the client.

The captcha token can be used to generate an image that depicts the captcha challenge, using the render() function in this module.

When the user enters an answer to the challenge, the answer can be checked against the token using the check() function. If the token is expired, or cannot be decrypted for some reason (e.g. forgery, change of IP address), an InvalidCaptchaToken exception is raised. If the token can be interpreted but the value is incorrect, an InvalidCaptchaValue exception is raised.

This was implemented as a stand-alone module in case we want to generalize it for use elsewhere.

exception accounts.stateless_captcha.InvalidCaptchaToken[source]

Bases: ValueError

A token was passed that is either expired or corrupted.

exception accounts.stateless_captcha.InvalidCaptchaValue[source]

Bases: ValueError

The passed value did not match the associated captcha token.

accounts.stateless_captcha.check(token, value, secret, ip_address)[source]

Evaluate whether a value matches a captcha token.

Parameters:
  • token (str) – A captcha token (see new()).
  • value (str) – The value of the captcha challenge (i.e. the text that the user is asked to enter).
  • secret (str) – The captcha secret used to generate the token.
  • ip_address (str) – The client IP address used to generate the token.
Raises:
  • InvalidCaptchaValue – If the passed value does not match the challenge contained in the token, this exception is raised.
  • InvalidCaptchaToken – Raised if the token is malformed, expired, or the IP address does not match the one used to generate the token.
Return type:

None
accounts.stateless_captcha.new(secret, ip_address, expires=300)[source]

Generate a captcha token.

Parameters:
  • secret (str) – Used to encrypt the captcha challenge.
  • ip_address (str) – The client IP address, also used to encrypt the token.
  • expires (int) – Number of seconds for which the token is valid. Default is 300 (5 minutes).
Returns:

A captcha token, which contains a captcha challenge and expiration.
Return type:

str
Return type:

str
accounts.stateless_captcha.render(token, secret, ip_address, font=None)[source]

Render a captcha image using the value in a captcha token.

Parameters:
  • token (str) – A captcha token (see new()).
  • secret (str) – The captcha secret used to generate the token.
  • ip_address (str) – The client IP address used to generate the token.
Returns:

PNG image data.
Return type:

io.BytesIO
Raises:

InvalidCaptchaToken – Raised if the token is malformed, expired, or the IP address does not match the one used to generate the token.
Return type:

BytesIO
accounts.stateless_captcha.unpack(token, secret, ip_address)[source]

Unpack a captcha token, and get the target value.

Parameters:
  • token (str) – A captcha token (see new()).
  • secret (str) – The captcha secret used to generate the token.
  • ip_address (str) – The client IP address used to generate the token.
Returns:

The captcha challenge (i.e. the text that the user is asked to enter).
Return type:

str
Raises:

InvalidCaptchaToken – Raised if the token is malformed, expired, or the IP address does not match the one used to generate the token.
Return type:

str