1Package captcha
  2=====================
  3
  4**:warning: Warning: this captcha can be broken by advanced OCR captcha breaking algorithms.**
  5
  6	import "github.com/dchest/captcha"
  7
  8Package captcha implements generation and verification of image and audio
  9CAPTCHAs.
 10
 11A captcha solution is the sequence of digits 0-9 with the defined length.
 12There are two captcha representations: image and audio.
 13
 14An image representation is a PNG-encoded image with the solution printed on
 15it in such a way that makes it hard for computers to solve it using OCR.
 16
 17An audio representation is a WAVE-encoded (8 kHz unsigned 8-bit) sound with the
 18spoken solution (currently in English, Russian, Chinese, and Japanese). To make
 19it hard for computers to solve audio captcha, the voice that pronounces numbers
 20has random speed and pitch, and there is a randomly generated background noise
 21mixed into the sound.
 22
 23This package doesn't require external files or libraries to generate captcha
 24representations; it is self-contained.
 25
 26To make captchas one-time, the package includes a memory storage that stores
 27captcha ids, their solutions, and expiration time. Used captchas are removed
 28from the store immediately after calling Verify or VerifyString, while
 29unused captchas (user loaded a page with captcha, but didn't submit the
 30form) are collected automatically after the predefined expiration time.
 31Developers can also provide custom store (for example, which saves captcha
 32ids and solutions in database) by implementing Store interface and
 33registering the object with SetCustomStore.
 34
 35Captchas are created by calling New, which returns the captcha id.  Their
 36representations, though, are created on-the-fly by calling WriteImage or
 37WriteAudio functions. Created representations are not stored anywhere, but
 38subsequent calls to these functions with the same id will write the same
 39captcha solution. Reload function will create a new different solution for the
 40provided captcha, allowing users to "reload" captcha if they can't solve the
 41displayed one without reloading the whole page.  Verify and VerifyString are
 42used to verify that the given solution is the right one for the given captcha
 43id.
 44
 45Server provides an http.Handler which can serve image and audio
 46representations of captchas automatically from the URL. It can also be used
 47to reload captchas.  Refer to Server function documentation for details, or
 48take a look at the example in "capexample" subdirectory.
 49
 50
 51Examples
 52--------
 53
 54![Image](https://github.com/dchest/captcha/raw/master/capgen/example.png)
 55
 56[Audio](https://github.com/dchest/captcha/raw/master/capgen/example.wav)
 57
 58
 59Constants
 60---------
 61
 62``` go
 63const (
 64    // Default number of digits in captcha solution.
 65    DefaultLen = 6
 66    // The number of captchas created that triggers garbage collection used
 67    // by default store.
 68    CollectNum = 100
 69    // Expiration time of captchas used by default store.
 70    Expiration = 10 * time.Minute
 71)
 72```
 73
 74``` go
 75const (
 76    // Standard width and height of a captcha image.
 77    StdWidth  = 240
 78    StdHeight = 80
 79)
 80```
 81
 82
 83Variables
 84---------
 85
 86``` go
 87var (
 88    ErrNotFound = errors.New("captcha: id not found")
 89)
 90```
 91
 92
 93
 94Functions
 95---------
 96
 97### func New
 98
 99	func New() string
100	
101New creates a new captcha with the standard length, saves it in the internal
102storage and returns its id.
103
104### func NewLen
105
106	func NewLen(length int) (id string)
107	
108NewLen is just like New, but accepts length of a captcha solution as the
109argument.
110
111### func RandomDigits
112
113	func RandomDigits(length int) (b []byte)
114	
115RandomDigits returns a byte slice of the given length containing
116pseudorandom numbers in range 0-9. The slice can be used as a captcha
117solution.
118
119### func Reload
120
121	func Reload(id string) bool
122	
123Reload generates and remembers new digits for the given captcha id.  This
124function returns false if there is no captcha with the given id.
125
126After calling this function, the image or audio presented to a user must be
127refreshed to show the new captcha representation (WriteImage and WriteAudio
128will write the new one).
129
130### func Server
131
132	func Server(imgWidth, imgHeight int) http.Handler
133	
134Server returns a handler that serves HTTP requests with image or
135audio representations of captchas. Image dimensions are accepted as
136arguments. The server decides which captcha to serve based on the last URL
137path component: file name part must contain a captcha id, file extension —
138its format (PNG or WAV).
139
140For example, for file name "LBm5vMjHDtdUfaWYXiQX.png" it serves an image captcha
141with id "LBm5vMjHDtdUfaWYXiQX", and for "LBm5vMjHDtdUfaWYXiQX.wav" it serves the
142same captcha in audio format.
143
144To serve a captcha as a downloadable file, the URL must be constructed in
145such a way as if the file to serve is in the "download" subdirectory:
146"/download/LBm5vMjHDtdUfaWYXiQX.wav".
147
148To reload captcha (get a different solution for the same captcha id), append
149"?reload=x" to URL, where x may be anything (for example, current time or a
150random number to make browsers refetch an image instead of loading it from
151cache).
152
153By default, the Server serves audio in English language. To serve audio
154captcha in one of the other supported languages, append "lang" value, for
155example, "?lang=ru".
156
157### func SetCustomStore
158
159	func SetCustomStore(s Store)
160	
161SetCustomStore sets custom storage for captchas, replacing the default
162memory store. This function must be called before generating any captchas.
163
164### func Verify
165
166	func Verify(id string, digits []byte) bool
167	
168Verify returns true if the given digits are the ones that were used to
169create the given captcha id.
170
171The function deletes the captcha with the given id from the internal
172storage, so that the same captcha can't be verified anymore.
173
174### func VerifyString
175
176	func VerifyString(id string, digits string) bool
177	
178VerifyString is like Verify, but accepts a string of digits.  It removes
179spaces and commas from the string, but any other characters, apart from
180digits and listed above, will cause the function to return false.
181
182### func WriteAudio
183
184	func WriteAudio(w io.Writer, id string, lang string) error
185	
186WriteAudio writes WAV-encoded audio representation of the captcha with the
187given id and the given language. If there are no sounds for the given
188language, English is used.
189
190### func WriteImage
191
192	func WriteImage(w io.Writer, id string, width, height int) error
193	
194WriteImage writes PNG-encoded image representation of the captcha with the
195given id. The image will have the given width and height.
196
197
198Types
199-----
200
201``` go
202type Audio struct {
203    // contains unexported fields
204}
205```
206
207
208### func NewAudio
209
210	func NewAudio(id string, digits []byte, lang string) *Audio
211	
212NewAudio returns a new audio captcha with the given digits, where each digit
213must be in range 0-9. Digits are pronounced in the given language. If there
214are no sounds for the given language, English is used.
215
216Possible values for lang are "en", "ja", "ru", "zh".
217
218### func (*Audio) EncodedLen
219
220	func (a *Audio) EncodedLen() int
221	
222EncodedLen returns the length of WAV-encoded audio captcha.
223
224### func (*Audio) WriteTo
225
226	func (a *Audio) WriteTo(w io.Writer) (n int64, err error)
227	
228WriteTo writes captcha audio in WAVE format into the given io.Writer, and
229returns the number of bytes written and an error if any.
230
231``` go
232type Image struct {
233    *image.Paletted
234    // contains unexported fields
235}
236```
237
238
239### func NewImage
240
241	func NewImage(id string, digits []byte, width, height int) *Image
242	
243NewImage returns a new captcha image of the given width and height with the
244given digits, where each digit must be in range 0-9.
245
246### func (*Image) WriteTo
247
248	func (m *Image) WriteTo(w io.Writer) (int64, error)
249	
250WriteTo writes captcha image in PNG format into the given writer.
251
252``` go
253type Store interface {
254    // Set sets the digits for the captcha id.
255    Set(id string, digits []byte)
256
257    // Get returns stored digits for the captcha id. Clear indicates
258    // whether the captcha must be deleted from the store.
259    Get(id string, clear bool) (digits []byte)
260}
261```
262
263An object implementing Store interface can be registered with SetCustomStore
264function to handle storage and retrieval of captcha ids and solutions for
265them, replacing the default memory store.
266
267It is the responsibility of an object to delete expired and used captchas
268when necessary (for example, the default memory store collects them in Set
269method after the certain amount of captchas has been stored.)
270
271### func NewMemoryStore
272
273	func NewMemoryStore(collectNum int, expiration time.Duration) Store
274	
275NewMemoryStore returns a new standard memory store for captchas with the
276given collection threshold and expiration time in seconds. The returned
277store must be registered with SetCustomStore to replace the default one.