base64Captcha

README

A flexible and various captcha package

Base64captcha supports any unicode character and can easily be customized to support Math Chinese Korean Japanese Russian Arabic etc.

1. 📖📖📖 Doc & Demo

• English
• 中文文档
• Playground

2. 🚀🚀🚀 Quick start

2.1 🎬🎬🎬 Use history version

Tag v1.2.2

go get github.com/mojocn/base64Captcha@v1.2.2

or edit your go.mod file to

github.com/mojocn/base64Captcha@v1.2.2

2.2 📥📥📥 Download package

go get -u github.com/mojocn/base64Captcha

For Gopher from mainland China without VPN go get golang.org/x/image failure solution:

• go version > 1.11
• set env GOPROXY=https://goproxy.io

2.3 🏂🏂🏂 How to code with base64Captcha

2.3.1 🏇🏇🏇 Implement Store interface or use build-in memory store

• Build-in Memory Store

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

	// Get returns stored digits for the captcha id. Clear indicates
	// whether the captcha must be deleted from the store.
	Get(id string, clear bool) string
	
    //Verify captcha's answer directly
	Verify(id, answer string, clear bool) bool
}

2.3.2 🏄🏄🏄 Implement Driver interface or use one of build-in drivers

There are some build-in drivers:

1. Build-in Driver Digit
2. Build-in Driver String
3. Build-in Driver Math
4. Build-in Driver Chinese

// Driver captcha interface for captcha engine to to write staff
type Driver interface {
	//DrawCaptcha draws binary item
	DrawCaptcha(content string) (item Item, err error)
	//GenerateIdQuestionAnswer creates rand id, content and answer
	GenerateIdQuestionAnswer() (id, q, a string)
}

2.3.3 🚴🚴🚴 ‍Core code captcha.go

captcha.go is the entry of base64Captcha which is quite simple.

package base64Captcha

import (
	"math/rand"
	"time"
)

func init() {
	//init rand seed
	rand.Seed(time.Now().UnixNano())
}

// Captcha captcha basic information.
type Captcha struct {
	Driver Driver
	Store  Store
}

//NewCaptcha creates a captcha instance from driver and store
func NewCaptcha(driver Driver, store Store) *Captcha {
	return &Captcha{Driver: driver, Store: store}
}

//Generate generates a random id, base64 image string or an error if any
func (c *Captcha) Generate() (id, b64s string, err error) {
	id,content, answer := c.Driver.GenerateIdQuestionAnswer()
	item, err := c.Driver.DrawCaptcha(content)
	if err != nil {
		return "", "", err
	}
	c.Store.Set(id, answer)
	b64s = item.EncodeB64string()
	return
}

//Verify by a given id key and remove the captcha value in store,
//return boolean value.
//if you has multiple captcha instances which share a same store.
//You may want to call `store.Verify` method instead.
func (c *Captcha) Verify(id, answer string, clear bool) (match bool) {
	match = c.Store.Get(id, clear) == answer
	return
}

2.3.4 🚵🚵🚵 ‍Generate Base64(image/audio) string

func (c *Captcha) Generate() (id, b64s string, err error) {
	id,content, answer := c.Driver.GenerateIdQuestionAnswer()
	item, err := c.Driver.DrawCaptcha(content)
	if err != nil {
		return "", "", err
	}
	c.Store.Set(id, answer)
	b64s = item.EncodeB64string()
	return
}

2.3.5 🤸🤸🤸 Verify Answer

//if you has multiple captcha instances which shares a same store. You may want to use `store.Verify` method instead.
//Verify by given id key and remove the captcha value in store, return boolean value.
func (c *Captcha) Verify(id, answer string, clear bool) (match bool) {
	match = c.Store.Get(id, clear) == answer
	return
}

2.3.6 🏃🏃🏃 ‍Full Example

// example of HTTP server that uses the captcha package.
package main

import (
	"encoding/json"
	"fmt"
	"github.com/mojocn/base64Captcha"
	"log"
	"net/http"
)

//configJsonBody json request body.
type configJsonBody struct {
	Id            string
	CaptchaType   string
	VerifyValue   string
	DriverAudio   *base64Captcha.DriverAudio
	DriverString  *base64Captcha.DriverString
	DriverChinese *base64Captcha.DriverChinese
	DriverMath    *base64Captcha.DriverMath
	DriverDigit   *base64Captcha.DriverDigit
}

var store = base64Captcha.DefaultMemStore

// base64Captcha create http handler
func generateCaptchaHandler(w http.ResponseWriter, r *http.Request) {
	//parse request parameters
	decoder := json.NewDecoder(r.Body)
	var param configJsonBody
	err := decoder.Decode(&param)
	if err != nil {
		log.Println(err)
	}
	defer r.Body.Close()
	var driver base64Captcha.Driver

	//create base64 encoding captcha
	switch param.CaptchaType {
	case "audio":
		driver = param.DriverAudio
	case "string":
		driver = param.DriverString.ConvertFonts()
	case "math":
		driver = param.DriverMath.ConvertFonts()
	case "chinese":
		driver = param.DriverChinese.ConvertFonts()
	default:
		driver = param.DriverDigit
	}
	c := base64Captcha.NewCaptcha(driver, store)
	id, b64s, err := c.Generate()
	body := map[string]interface{}{"code": 1, "data": b64s, "captchaId": id, "msg": "success"}
	if err != nil {
		body = map[string]interface{}{"code": 0, "msg": err.Error()}
	}
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	json.NewEncoder(w).Encode(body)
}

// base64Captcha verify http handler
func captchaVerifyHandle(w http.ResponseWriter, r *http.Request) {

	//parse request json body
	decoder := json.NewDecoder(r.Body)
	var param configJsonBody
	err := decoder.Decode(&param)
	if err != nil {
		log.Println(err)
	}
	defer r.Body.Close()
	//verify the captcha
	body := map[string]interface{}{"code": 0, "msg": "failed"}
	if store.Verify(param.Id, param.VerifyValue, true) {
		body = map[string]interface{}{"code": 1, "msg": "ok"}
	}

	//set json response
	w.Header().Set("Content-Type", "application/json; charset=utf-8")

	json.NewEncoder(w).Encode(body)
}

//start a net/http server
func main() {
	//serve Vuejs+ElementUI+Axios Web Application
	http.Handle("/", http.FileServer(http.Dir("./static")))

	//api for create captcha
	http.HandleFunc("/api/getCaptcha", generateCaptchaHandler)

	//api for verify captcha
	http.HandleFunc("/api/verifyCaptcha", captchaVerifyHandle)

	fmt.Println("Server is at :8777")
	if err := http.ListenAndServe(":8777", nil); err != nil {
		log.Fatal(err)
	}
}

2.3.7 Example Use Etcd as store

captcha with etcd database as store

3. 🎨🎨🎨 Customization

You can customize your captcha display image by implementing interface driver and interface item.

There are some example for your reference.

1. DriverMath
2. DriverChinese
3. ItemChar

You can even design the captcha struct to whatever you prefer.

4. 💖💖💖 Thanks

• dchest/captha
• @slayercat
• @amzyang
• @Luckyboys
• @hi-sb

5. 🍭🍭🍭 Licence

base64Captcha source code is licensed under the Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html).

Documentation

Index

• Constants
• Variables
• func NewDriverMath(height int, width int, noiseCount int, showLineOptions int, ...) (*driverMath, error)
• func NewDriverString(height int, width int, noiseCount int, showLineOptions int, length int, ...) (*driverString, error)
• func RandColor() color.RGBA
• func RandDeepColor() color.RGBA
• func RandLightColor() color.RGBA
• func RandText(size int, sourceChars string) string
• func RandomId() string
• type Driver
• type EmbeddedFontsStorage
  • func NewEmbeddedFontsStorage(fs embed.FS) *EmbeddedFontsStorage
  • func (s *EmbeddedFontsStorage) LoadFontByName(name string) *truetype.Font
  • func (s *EmbeddedFontsStorage) LoadFontsByNames(assetFontNames []string) []*truetype.Font
• type FontsStorage
• type Item
• type ItemChar
  • func NewItemChar(w int, h int, bgColor color.RGBA) *ItemChar
  • func (item *ItemChar) EncodeBinary() []byte
  • func (item *ItemChar) WriteTo(w io.Writer) (int64, error)
• type Store
  • func NewMemoryStore(collectNum int, expiration time.Duration) Store
• type StoreSyncMap
  • func NewStoreSyncMap(liveTime time.Duration) *StoreSyncMap
  • func (s StoreSyncMap) Get(id string, clear bool) string
  • func (s StoreSyncMap) Set(id string, value string)
  • func (s StoreSyncMap) Verify(id, answer string, clear bool) bool

Constants

const (

	//TxtNumbers chacters for numbers.
	TxtNumbers = "012346789"
	//TxtAlphabet characters for alphabet.
	TxtAlphabet = "ABCDEFGHJKMNOQRSTUVXYZabcdefghjkmnoqrstuvxyz"
	//TxtSimpleCharaters simple numbers and alphabet
	TxtSimpleCharaters = "13467ertyiadfhjkxcvbnERTYADFGHJKXCVBN"
	//TxtChineseCharaters makes characters in chinese
	TxtChineseCharaters = "的一是在不了有和人这中大为上个国我以要他" +
		"时来用们生到作地于出就分对成会可主发年动" +
		"同工也能下过子说产种面而方后多定行学法所" +
		"民得经十三之进着等部度家电力里如水化高自" +
		"二理起小物现实加量都两体制机当使点从业本" +
		"去把性好应开它合还因由其些然前外天政四日" +
		"那社义事平形相全表间样与关各重新线内数正" +
		"心反你明看原又么利比或但质气第向道命此变" +
		"条只没结解问意建月公无系军很情者最立代想" +
		"已通并提直题党程展五果料象员革位入常文总" +
		"次品式活设及管特件长求老头基资边流路级少" +
		"图山统接知较将组见计别她手角期根论运农指" +
		"几九区强放决西被干做必战先回则任取据处队" +
		"南给色光门即保治北造百规热领七海口东导器" +
		"压志世金增争济阶油思术极交受联什认六共权" +
		"收证改清己美再采转更单风切打白教速花带安" +
		"场身车例真务具万每目至达走积示议声报斗完" +
		"类八离华名确才科张信马节话米整空元况今集" +
		"温传土许步群广石记需段研界拉林律叫且究观" +
		"越织装影算低持音众书布复容儿须际商非验连" +
		"断深难近矿千周委素技备半办青省列习响约支" +
		"般史感劳便团往酸历市克何除消构府称太准精" +
		"值号率族维划选标写存候毛亲快效斯院查江型" +
		"眼王按格养易置派层片始却专状育厂京识适属" +
		"圆包火住调满县局照参红细引听该铁价严龙飞"

	//MimeTypeAudio output base64 mine-type.
	MimeTypeAudio = "audio/wav"
	//MimeTypeImage output base64 mine-type.
	MimeTypeImage = "image/png"
	//Emoji is a source string for randTxt
	Emoji = "" /* 268-byte string literal not displayed */
)

const (
	//OptionShowHollowLine shows hollow line
	OptionShowHollowLine = 2
	//OptionShowSlimeLine shows slime line
	OptionShowSlimeLine = 4
	//OptionShowSineLine shows sine line
	OptionShowSineLine = 8
)

Variables

var (
	// GCLimitNumber The number of captchas created that triggers garbage collection used by default store.
	GCLimitNumber = 10240
	// Expiration time of captchas used by default store.
	Expiration = 10 * time.Minute
	// DefaultMemStore is a shared storage for captchas, generated by New function.
	DefaultMemStore = NewMemoryStore(GCLimitNumber, Expiration)
)

Functions

func NewDriverMath

func NewDriverMath(height int, width int, noiseCount int, showLineOptions int, bgColor *color.RGBA, fontsStorage FontsStorage, fonts []string) (*driverMath, error)

NewDriverMath creates a driver of math

func NewDriverString

func NewDriverString(height int, width int, noiseCount int, showLineOptions int, length int, source string, bgColor *color.RGBA, fontsStorage FontsStorage, fonts []string) (*driverString, error)

NewDriverString creates driver

func RandColor

func RandColor() color.RGBA

RandColor get random color. 生成随机颜色.

func RandDeepColor

func RandDeepColor() color.RGBA

RandDeepColor get random deep color. 随机生成深色系.

func RandLightColor

func RandLightColor() color.RGBA

RandLightColor get random ligth color. 随机生成浅色.

func RandText

func RandText(size int, sourceChars string) string

RandText creates random text of given size.

func RandomId

func RandomId() string

RandomId returns a new random id key string.

Types

type Driver

type Driver interface {
	//DrawCaptcha draws binary item
	DrawCaptcha(content string) (item Item, err error)
	//GenerateIdQuestionAnswer creates rand id, content and answer
	GenerateIdQuestionAnswer() (id, q, a string)
}

Driver captcha interface for captcha engine to to write staff

type EmbeddedFontsStorage

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

func NewEmbeddedFontsStorage

func NewEmbeddedFontsStorage(fs embed.FS) *EmbeddedFontsStorage

func (*EmbeddedFontsStorage) LoadFontByName

func (s *EmbeddedFontsStorage) LoadFontByName(name string) *truetype.Font

func (*EmbeddedFontsStorage) LoadFontsByNames

func (s *EmbeddedFontsStorage) LoadFontsByNames(assetFontNames []string) []*truetype.Font

LoadFontsByNames import fonts from dir. make the simple-font(RitaSmith.ttf) the first font of trueTypeFonts.

type FontsStorage

type FontsStorage interface {
	// LoadFontByName returns the font from the storage
	LoadFontByName(name string) *truetype.Font

	// LoadFontsByNames returns multiple fonts from storage
	LoadFontsByNames(assetFontNames []string) []*truetype.Font
}

FontsStorage interface for working with fonts

type Item

type Item interface {
	// WriteTo writes to a writer
	WriteTo(w io.Writer) (n int64, err error)
	// EncodeBinary encodes as raw byte slice
	EncodeBinary() []byte
}

Item is captcha item interface

type ItemChar

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

ItemChar captcha item of unicode characters

func NewItemChar

func NewItemChar(w int, h int, bgColor color.RGBA) *ItemChar

NewItemChar creates a captcha item of characters

func (*ItemChar) EncodeBinary

func (item *ItemChar) EncodeBinary() []byte

BinaryEncoding encodes an image to PNG and returns a byte slice.

func (*ItemChar) WriteTo

func (item *ItemChar) WriteTo(w io.Writer) (int64, error)

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

type Store

type Store interface {
	// Set sets the digits for the captcha id.
	Set(id string, value string) error

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

	//Verify captcha's answer directly
	Verify(id, answer string, clear bool) bool
}

Store 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.

type StoreSyncMap

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

StoreSyncMap use sync.Map as store

func NewStoreSyncMap

func NewStoreSyncMap(liveTime time.Duration) *StoreSyncMap

NewStoreSyncMap new a instance

func (StoreSyncMap) Get

func (s StoreSyncMap) Get(id string, clear bool) string

Set a string value

func (StoreSyncMap) Set

func (s StoreSyncMap) Set(id string, value string)

Get get a string value

func (StoreSyncMap) Verify

func (s StoreSyncMap) Verify(id, answer string, clear bool) bool

Verify check a string value