captcha

Documentation

Overview

Package captcha implements generation and verification of image and audio CAPTCHAs.

A captcha solution is the sequence of digits 0-9 with the defined length. There are two captcha representations: image and audio.

An image representation 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.

An audio representation is a WAVE-encoded (8 kHz unsigned 8-bit) sound with the spoken solution (currently in English, Russian, Chinese, and Japanese). To make it hard for computers to solve audio captcha, the voice that pronounces numbers has random speed and pitch, and there is a randomly generated background noise mixed into the sound.

This package doesn't require external files or libraries to generate captcha representations; it is self-contained.

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 "capexample" subdirectory.

Index

• Constants
• Variables
• func New() string
• func NewLen(length int) (code string)
• func RandomDigits(length int) []byte
• func WriteAudio(w io.Writer, code string, lang string) error
• func WriteImage(w io.Writer, code string, width, height int) error
• type Audio
  • func NewAudio(digits []byte, lang string) *Audio
  • func (a *Audio) EncodedLen() int
  • func (a *Audio) WriteTo(w io.Writer) (n int64, err error)
• type Image
  • func NewImage(digits []byte, width, height int) *Image
  • func (m *Image) WriteTo(w io.Writer) (int64, error)

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
)

const (
	// Standard width and height of a captcha image.
	StdWidth  = 240
	StdHeight = 80
)

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) (code string)

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

func RandomDigits

func RandomDigits(length int) []byte

RandomDigits returns a byte slice of the given length containing pseudorandom numbers in range 0-9. The slice can be used as a captcha solution.

func WriteAudio

func WriteAudio(w io.Writer, code string, lang string) error

WriteAudio writes WAV-encoded audio representation of the captcha with the given id and the given language. If there are no sounds for the given language, English is used.

func WriteImage

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

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

Types

type Audio

type Audio struct {
	// contains filtered or unexported fields
}

func NewAudio

func NewAudio(digits []byte, lang string) *Audio

NewAudio returns a new audio captcha with the given digits, where each digit must be in range 0-9. Digits are pronounced in the given language. If there are no sounds for the given language, English is used.

Possible values for lang are "en", "ja", "ru", "zh".

func (*Audio) EncodedLen

func (a *Audio) EncodedLen() int

EncodedLen returns the length of WAV-encoded audio captcha.

func (*Audio) WriteTo

func (a *Audio) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes captcha audio in WAVE format into the given io.Writer, and returns the number of bytes written and an error if any.

type Image

type Image struct {
	*image.Paletted
	// contains filtered or unexported fields
}

func NewImage

func NewImage(digits []byte, width, height int) *Image

NewImage returns a new captcha image of the given width and height with the given digits, where each digit must be in range 0-9.

func (*Image) WriteTo

func (m *Image) WriteTo(w io.Writer) (int64, error)

WriteTo writes captcha image in PNG format into the given writer.