README.md (view raw)
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
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.