captcha

README

Package captcha

This is a fork of https://github.com/dchest/captcha Original by Dmitry Chestnykh

import "github.com/ZiRo/captcha"

Package captcha implements generation and verification of image CAPTCHAs.

A captcha solution is the sequence of digits 0-9 and letters a-z, A-Z with a defined length.

The captcha is a PNG-encoded image with the solution printed on it in such a way that makes it hard for computers to solve it using OCR.

This package only requires font files. See github.com/ZiRo-/captcha/fontgen for details on how to get them. So, before you start generating captchas, you have to load a font:

	fn := libgocaptcha.LoadFontFromFile("Ubuntu-Mono.gob)
	if fn == nil {
		log.Fatalf("Couldn't load font file")
	}
	libgocaptcha.AddFont("font", fn)
	libgocaptcha.SetCharacterRange(libgocaptcha.MODULE_UPPER)

To make captchas one-time, the package includes a memory storage that stores captcha ids, their solutions, and expiration time. Used captchas are removed from the store immediately after calling Verify or VerifyString, while unused captchas (user loaded a page with captcha, but didn't submit the form) are collected automatically after the predefined expiration time. Developers can also provide custom store (for example, which saves captcha ids and solutions in database) by implementing Store interface and registering the object with SetCustomStore.

Captchas are created by calling New, which returns the captcha id. Their representations, though, are created on-the-fly by calling WriteImage. Created representations are not stored anywhere, but subsequent calls to these functions with the same id will write the same captcha solution. Reload function will create a new different solution for the provided captcha, allowing users to "reload" captcha if they can't solve the displayed one without reloading the whole page. Verify and VerifyString are used to verify that the given solution is the right one for the given captcha id.

Server provides an http.Handler which can serve image and audio representations of captchas automatically from the URL. It can also be used to reload captchas. Refer to Server function documentation for details, or take a look at the example in github.com/ZiRo-/captcha/capexample

C/C++ bindings

See https://github.com/ZiRo-/captcha/tree/master/libgocaptcha/C_bindings

Examples

Documentation

Overview

Package captcha implements generation and verification of image CAPTCHAs with custom fonts.

A captcha solution is the sequence of digits 0-9 and letters a-z, A-Z with a defined length.

The captcha is a PNG-encoded image with the solution printed on it in such a way that makes it hard for computers to solve it using OCR.

This package only requires font files. See https://github.com/ZiRo-/captcha/tree/master/fontgen for details on how to get them. So, before you start generating captchas, you have to load a font:

font, err := captcha.LoadFontFromFile("UbuntuMono.gob")
if err != nil {
	fmt.Println("Couldn't load font file")
}
captcha.AddFont("font", fn)

To make captchas one-time, the package includes a memory storage that stores captcha ids, their solutions, and expiration time. Used captchas are removed from the store immediately after calling Verify or VerifyString, while unused captchas (user loaded a page with captcha, but didn't submit the form) are collected automatically after the predefined expiration time. Developers can also provide custom store (for example, which saves captcha ids and solutions in database) by implementing Store interface and registering the object with SetCustomStore.

Captchas are created by calling New, which returns the captcha id. Their representations, though, are created on-the-fly by calling WriteImage or WriteAudio functions. Created representations are not stored anywhere, but subsequent calls to these functions with the same id will write the same captcha solution. Reload function will create a new different solution for the provided captcha, allowing users to "reload" captcha if they can't solve the displayed one without reloading the whole page. Verify and VerifyString are used to verify that the given solution is the right one for the given captcha id.

Server provides an http.Handler which can serve image and audio representations of captchas automatically from the URL. It can also be used to reload captchas. Refer to Server function documentation for details, or take a look at the example in https://github.com/ZiRo-/captcha/tree/master/capexample

Index

• Constants
• Variables
• func New() string
• func NewLen(length int) (id string)
• func Reload(id string) bool
• func Server(imgWidth, imgHeight int) http.Handler
• func SetCustomStore(s Store)
• func Verify(id string, digits []byte) bool
• func VerifyString(id string, digits string) bool
• func WriteImage(w io.Writer, id string, width, height int) error
• type Store
  • func NewMemoryStore(collectNum int, expiration time.Duration) Store

Constants

const (
	// Default number of digits in captcha solution.
	DefaultLen = 6
	// The number of captchas created that triggers garbage collection used
	// by default store.
	CollectNum = 100
	// Expiration time of captchas used by default store.
	Expiration = 10 * time.Minute
)

Variables

var (
	ErrNotFound = errors.New("captcha: id not found")
)

Functions

func New

func New() string

New creates a new captcha with the standard length, saves it in the internal storage and returns its id.

func NewLen

func NewLen(length int) (id string)

NewLen is just like New, but accepts length of a captcha solution as the argument.

func Reload

func Reload(id string) bool

Reload generates and remembers new digits for the given captcha id. This function returns false if there is no captcha with the given id.

After calling this function, the image or audio presented to a user must be refreshed to show the new captcha representation (WriteImage and WriteAudio will write the new one).

func Server

func Server(imgWidth, imgHeight int) http.Handler

Server returns a handler that serves HTTP requests with image of captchas. Image dimensions are accepted as arguments. The server decides which captcha to serve based on the last URL path component: file name part must contain a captcha id, file extension — its format (PNG).

For example, for file name "LBm5vMjHDtdUfaWYXiQX.png" it serves an image captcha with id "LBm5vMjHDtdUfaWYXiQX".

To serve a captcha as a downloadable file, the URL must be constructed in such a way as if the file to serve is in the "download" subdirectory: "/download/LBm5vMjHDtdUfaWYXiQX.png".

To reload captcha (get a different solution for the same captcha id), append "?reload=x" to URL, where x may be anything (for example, current time or a random number to make browsers refetch an image instead of loading it from cache).

func SetCustomStore

func SetCustomStore(s Store)

SetCustomStore sets custom storage for captchas, replacing the default memory store. This function must be called before generating any captchas.

func Verify

func Verify(id string, digits []byte) bool

Verify returns true if the given digits are the ones that were used to create the given captcha id.

The function deletes the captcha with the given id from the internal storage, so that the same captcha can't be verified anymore.

func VerifyString

func VerifyString(id string, digits string) bool

VerifyString is like Verify, but accepts a string of digits. It removes spaces and commas from the string, but any other characters, apart from digits and listed above, will cause the function to return false.

func WriteImage

func WriteImage(w io.Writer, id string, width, height int) error

WriteImage writes PNG-encoded image representation of the captcha with the given id. The image will have the given width and height.

Types

type Store

type Store interface {
	// Set sets the digits for the captcha id.
	Set(id string, digits []byte)

	// Get returns stored digits for the captcha id. Clear indicates
	// whether the captcha must be deleted from the store.
	Get(id string, clear bool) (digits []byte)
}

An object implementing Store interface can be registered with SetCustomStore function to handle storage and retrieval of captcha ids and solutions for them, replacing the default memory store.

It is the responsibility of an object to delete expired and used captchas when necessary (for example, the default memory store collects them in Set method after the certain amount of captchas has been stored.)

func NewMemoryStore

func NewMemoryStore(collectNum int, expiration time.Duration) Store

NewMemoryStore returns a new standard memory store for captchas with the given collection threshold and expiration time (duration). The returned store must be registered with SetCustomStore to replace the default one.