ginpow

Documentation

Index

• type Middleware
  • func New(m *Middleware) (*Middleware, error)
  • func (pow *Middleware) GenerateNonceMiddleware(c *gin.Context)
  • func (pow *Middleware) NonceHandler(c *gin.Context)
  • func (pow *Middleware) NonceHeaderMiddleware(c *gin.Context)
  • func (pow *Middleware) VerifyNonceMiddleware(c *gin.Context)
• type VerificationError
  • func (v *VerificationError) Error() string

Types

type Middleware

type Middleware struct {
	// NonceHeader is the name of the header on which to set a generated nonce.
	//   Defaults to `X-Nonce`
	NonceHeader string

	// NonceChecksumHeader is the name of the header on which to set a generated nonce.
	//   Defaults to `X-Nonce-Checksum`
	NonceChecksumHeader string

	// HashDifficultyHeader is the name of the header on which to set the difficulty.
	//   Defaults to `X-Hash-Difficulty`
	HashDifficultyHeader string

	// Pow is a gopow.Pow instance to handle proof of work implementation
	Pow *gopow.Pow

	// ExtractAll extracts all necessary data at once.
	//   Optional. If not set then uses the default methods defined in `ExtractData`,
	//   `ExtractNonce`, and `ExtractHash`. When ExtractAll is set, then `ExtractData`,
	//   `ExctractNonce`, `ExtractHash` is ignored.
	ExtractAll func(c *gin.Context) (nonce string, nonceChecksum string, data string, hash string, err error)

	// ExtractData extracts the data that the hash was generated against and
	//   passes it to do proof of work calculation.
	//   Required when `ExtractAll` isn't defined.
	ExtractData func(c *gin.Context) (string, error)

	// ExtractNonce extracts the nonce that is in the request.
	//   Defaults getting from header X-Nonce, X-Nonce-Checksum
	ExtractNonce func(c *gin.Context) (nonce string, nonceChecksum string, error error)

	// ExtractHash extracts the calculated hash calculated by the client.
	//   Defaults to getting from header X-Hash.
	ExtractHash func(c *gin.Context) (hash string, error error)

	// Difficulty sets the number of leading zeros required for a valid hash.
	//   Defaults to 0.
	Difficulty int

	// NonceLength sets the length of the nonce to be generated
	//   Defaults to 10.
	NonceLength int

	// Check is the flag to enable nonce checking
	//   Defaults to false.
	Check bool

	// Secret is a cryptographically secure random string to generate nonce checksums.
	//   only used when `Check` flag is true. Defaults to 256 bit cryptographically secure string.
	Secret string

	// the following is the keys in which to set nonces in gin.Context.
	// Defaults:
	//   NonceContextKey:          "nonce"
	//   NonceChecksumContextKey:  "nonceChecksum"
	//   HashDifficultyContextKey: "hashDifficulty"
	NonceContextKey          string
	NonceChecksumContextKey  string
	HashDifficultyContextKey string

	// the following is the keys in which to set nonces in data of Middleware.NonceHandler.
	// Defaults:
	//   NonceDataKey:          "nonce"
	//   NonceChecksumDataKey:  "nonce_checksum"
	//   HashDifficultyDataKey: "difficulty"
	NonceDataKey          string
	NonceChecksumDataKey  string
	HashDifficultyDataKey string

	// FailureStatusCode is the status code to send back to client
	//   when using default OnFailedVerification. defaults to 428.
	FailureStatusCode int

	// OnFailedVerification is called when a hash validation fails.
	//   By default request Aborts and returns with `Middleware.FailureStatusCode`.
	OnFailedVerification func(c *gin.Context, err *VerificationError)

	// Hash function for proof of work.
	//   Defaults to sha256
	Hash gopow.HashFunction

	// NonceGenerator returns a nonce.
	NonceGenerator gopow.NonceGenerator
}

Middleware provides a proof of work implementation. On failure, an error 428 response is returned. On success, the middleware passes to the next handler. Clients can request a nonce by posting a json or xml request to NonceHandler, or by reading the set headers on an endpoint that uses the NonceHeaderMiddleware

func New

func New(m *Middleware) (*Middleware, error)

New sets the config of a middleware. ExtractData definition is required.

func (*Middleware) GenerateNonceMiddleware

func (pow *Middleware) GenerateNonceMiddleware(c *gin.Context)

GenerateNonceMiddleware generates a nonce and sets it in the context. if other ginpow middleware is used after this middleware then it will use the nonce generated here.

func (*Middleware) NonceHandler

func (pow *Middleware) NonceHandler(c *gin.Context)

NonceHandler is the used by a client to get a nonce in JSON or XML depending on accept header

func (*Middleware) NonceHeaderMiddleware

func (pow *Middleware) NonceHeaderMiddleware(c *gin.Context)

NonceHeaderMiddleware is used by a client to get a nonce embedded in the header of a request

func (*Middleware) VerifyNonceMiddleware

func (pow *Middleware) VerifyNonceMiddleware(c *gin.Context)

VerifyNonceMiddleware validates a hash given a nonce, data string, difficulty, and, if `Middleware.Check == true`, nonce checksum. On failure, it will call OnVerifiedFailed method. By default will Abort response with status code 428

type VerificationError

type VerificationError struct {
	Hash          string
	Nonce         string
	NonceChecksum string
	Difficulty    int
	Reason        string
}

VerificationError reports the parameters that caused a verification to fail. Does _not_ include data parameter.

func (*VerificationError) Error

func (v *VerificationError) Error() string