auth

README

auth - Easy to Use Authentication Package

This package provides quick easy to use methods and functions to perform various authentication activities in applications.

Inspiration

This package draws inspiration from the Udemy Course - Web Authentication, Encryption, JWT, HMAC, & OAuth With Go by Created by Todd McLeod and Daniel Hoffmann.

The gist of the learning from this course has been incorporated into this package.

License

Copyright 2020 Abhijit Bose. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package auth is a authentication helper that supports multiple types of applications.

Index

• Constants
• Variables
• func Decode(f *EncodeIt, value string) ([]byte, error)
• func Digest(d DigestIt, data []byte, opts ...DigestOptions) ([]byte, error)
• func Encode(f *EncodeIt, data []byte) string
• func GetHSToken(session string, key []byte, d DigestIt, opt ...HSTokenOptions) (string, error)
• func GetRandom(size int) ([]byte, error)
• func PasswordCheck(d DigestIt, pass string, dig []byte, opts ...DigestOptions) error
• func PasswordHash(d DigestIt, pass string, opts ...DigestOptions) ([]byte, error)
• func Pbkdf2(password []byte, d DigestIt, opt ...Pbkdf2Options) (result []byte, salt []byte, err error)
• func RandString(size int) (s string, err error)
• func RegisterDigestFunction(name string, f DigestIt)
• func RegisterEncoder(f *EncodeIt)
• func UUIDv4() (string, error)
• type Auth
• type DigestIt
  • func GetDigestFunction(name string) (f DigestIt)
• type DigestOptions
  • func WithBcryptCost(cost int) DigestOptions
  • func WithDigest(digest []byte) DigestOptions
  • func WithHMACKey(key []byte) DigestOptions
• type EncodeIt
  • func GetEncoder(name string) (f *EncodeIt)
  • func (e *EncodeIt) Create(data []byte, encode interface{}) (output []byte, err error)
  • func (e *EncodeIt) Set(method string, key interface{}) error
  • func (e *EncodeIt) Verify(value []byte, bias interface{}) (data []byte, iBias interface{}, err error)
• type HSTokenClaims
  • func CheckHSToken(signedToken string, key []byte, d DigestIt) (session string, claim *HSTokenClaims, err error)
  • func (c *HSTokenClaims) Valid() error
• type HSTokenOptions
  • func HSTokenDuration(d time.Duration) HSTokenOptions
  • func HSTokenExpiry(ex time.Time) HSTokenOptions
  • func HSTokenWith(ID, audience, issuer, subject string) HSTokenOptions
• type Pbkdf2Options
  • func Pbkdf2Salt(buf []byte) Pbkdf2Options
  • func Pbkdf2With(rounds, size int) Pbkdf2Options

Constants

const (
	// BcryptDefaultCost is the Bcrypt Default Cost where the performace is optimal
	BcryptDefaultCost = bcrypt.DefaultCost
	// BcryptMaxCost is the Bcrypt Maximum Cost with Longest Time
	BcryptMaxCost = bcrypt.MaxCost
	// BcryptMinCost is the Bcrypt Minimum Cost with Shortest time
	BcryptMinCost = bcrypt.MinCost
	// MethodMD5 describes the MD5 Hashing Algorithm
	MethodMD5 = "MD5"
	// MethodSHA1 describes the SHA1 Hashing Algorithm
	MethodSHA1 = "SHA1"
	// MethodSHA224 describes the SHA224 Hashing Algorithm
	MethodSHA224 = "SHA224"
	// MethodSHA256 describes the SHA256 Hashing Algorithm
	MethodSHA256 = "SHA256"
	// MethodSHA384 describes the SHA384 Hashing Algorithm
	MethodSHA384 = "SHA384"
	// MethodSHA512 describes the SHA512 Hashing Algorithm
	MethodSHA512 = "SHA512"
	// MethodBcrypt describes the bcrypt Hashing Algorithm
	MethodBcrypt = "bcrypt"
)

const (
	// Pbkdf2MinSize defines the minimum size of the Salt and Output
	Pbkdf2MinSize = 8
	// Pbkdf2MinRounds defines the minimum number of iterations for the
	// PBKDF2 key derivation process
	Pbkdf2MinRounds = 8
)

const (

	// HSTokenDefaultExpiry specifies the Minimum duration for which HSToken is valid
	HSTokenDefaultExpiry = 1 * time.Minute
)

Variables

var (
	Md5    *hashFn
	Sha1   *hashFn
	Sha224 *hashFn
	Sha256 *hashFn
	Sha384 *hashFn
	Sha512 *hashFn
	Bcrypt *bcryptFn
)

List of Hash Functions

var ErrNotImplemented = fmt.Errorf("error functionality not implemented yet")

ErrNotImplemented occurs when an Un-implemented feature is called on

var ErrNotInitialized = fmt.Errorf("error this construct is not initialized")

ErrNotInitialized occurs when an Authentication process or function tries to access an un-initialized data parameter or construct.

var ErrNotSupported = fmt.Errorf("error the option or operation is not supported")

ErrNotSupported occurs when a particular feature is not implemented or

logically not supported in the current context

var ErrParameter = fmt.Errorf("error in supplied parameters")

ErrParameter occurs when there are issues with the supplied parameter in any function.

Functions

func Decode

func Decode(f *EncodeIt, value string) ([]byte, error)

Decode is the Generic DecodeFromString function for all encoded values supported

func Digest

func Digest(d DigestIt, data []byte, opts ...DigestOptions) ([]byte, error)

Digest is the generic function for obtaining various type of HASH function operations on the data

func Encode

func Encode(f *EncodeIt, data []byte) string

Encode is Generic EncodeToString function for All byte Arrays

func GetHSToken

func GetHSToken(session string, key []byte, d DigestIt, opt ...HSTokenOptions) (string, error)

GetHSToken function Provides a way to generate a JWT of HS256, HS384 and HS512 type tokens

func GetRandom

func GetRandom(size int) ([]byte, error)

GetRandom returns a cryptographically safe randome numbers byte array with the size specified

func PasswordCheck

func PasswordCheck(d DigestIt, pass string, dig []byte, opts ...DigestOptions) error

PasswordCheck function is used to verify the password against the precalculated digest.

func PasswordHash

func PasswordHash(d DigestIt, pass string, opts ...DigestOptions) ([]byte, error)

PasswordHash is used to generated cryptographically secure digest from the supplied password and also verify the digest.

func Pbkdf2

func Pbkdf2(password []byte, d DigestIt, opt ...Pbkdf2Options) (
	result []byte,
	salt []byte,
	err error,
)

Pbkdf2 function performs the PBKDF2 operation with given optional functions

func RandString

func RandString(size int) (s string, err error)

RandString generates a random string array based on the given size

func RegisterDigestFunction

func RegisterDigestFunction(name string, f DigestIt)

RegisterDigestFunction adds the specific Hash generation functions in the global list. It is typically run during init() stage.

func RegisterEncoder

func RegisterEncoder(f *EncodeIt)

RegisterEncoder updates the list of Encoders available. This is typically called during init() stage.

func UUIDv4

func UUIDv4() (string, error)

UUIDv4 function helps to generate UUID using V4 algorithm

Types

type Auth

type Auth interface {

	// Create function generates the Authentication Entity by processing
	// incoming data and the specific 'bias'.
	Create(data []byte, bias interface{}) (output []byte, err error)

	// Verify function checks the Authentication Entity by processing
	// it with the optional incoming 'bias'. It also recovers the original
	// 'data' and 'bias' used to create the Authentication Entity.
	Verify(value []byte, bias interface{}) (data []byte, iBias interface{}, err error)

	// Set function configures the Authentication Entity creation and
	// verification process. It also accepts the static "Key" that needs
	// to be employed while processing the Authentication Entity.
	Set(method string, key interface{}) error
}

Auth is the generic interface that would be implemented by the various authentication algorithms and classifications.

The term "Authentication Entity" refers to a token, pass, or a Unique piece of information that provides Identity, and Authorization status of the bearer.

type DigestIt

type DigestIt interface {

	// Name Returns the Name in String for the given Hash Function
	Name() string

	// Get function takes in the byte array of arbitrary Size and
	// process it into a digest of fix size
	Get([]byte) ([]byte, error)

	// Auth Interface is Implemented here
	Auth
}

DigestIt interface defines the way by which Hash function coverts byte array of arbitrary size to a byte array of a fixed size called the "hash value", "hash", or "message digest"

func GetDigestFunction

func GetDigestFunction(name string) (f DigestIt)

GetDigestFunction fetches the respective Hash generation function using its pre registed name.

type DigestOptions

type DigestOptions func(DigestIt) DigestIt

DigestOptions provides a functional Option for attribute modification functions

func WithBcryptCost

func WithBcryptCost(cost int) DigestOptions

WithBcryptCost helps to implement Alternative Bcrypt operation

func WithDigest

func WithDigest(digest []byte) DigestOptions

WithDigest helps to implement Verification as part of Digest operations

func WithHMACKey

func WithHMACKey(key []byte) DigestOptions

WithHMACKey helps to implement HMAC operation

type EncodeIt

type EncodeIt struct {
	Name string
	// To(EncodeToString) converts the Supplied byte array to the specific
	// encode Format string
	To func(src []byte) string

	// From(DecodeString) converts the Supplied string back to its byte array form
	From func(s string) ([]byte, error)
}

EncodeIt is the String format encode function for byte Array encoders

var (
	Hex       *EncodeIt
	Base64    *EncodeIt
	Base64URL *EncodeIt
)

List of Encoders Supported

func GetEncoder

func GetEncoder(name string) (f *EncodeIt)

GetEncoder fetches the specific encoder from the List of Encoders

func (*EncodeIt) Create

func (e *EncodeIt) Create(data []byte, encode interface{}) (output []byte, err error)

Create method from the Auth Interface

func (*EncodeIt) Set

func (e *EncodeIt) Set(method string, key interface{}) error

Set Method from the Auth Interface

func (*EncodeIt) Verify

func (e *EncodeIt) Verify(value []byte, bias interface{}) (data []byte, iBias interface{}, err error)

Verify method from the Auth Interface

type HSTokenClaims

type HSTokenClaims struct {
	Session string `json:"session"`
	jwt.StandardClaims
}

HSTokenClaims provides the required storage for JWT claims

func CheckHSToken

func CheckHSToken(signedToken string, key []byte, d DigestIt) (
	session string,
	claim *HSTokenClaims,
	err error,
)

CheckHSToken function provides a way to verify the signed token and decode

the underlying data.

func (*HSTokenClaims) Valid

func (c *HSTokenClaims) Valid() error

Valid method for the `jwt.Claims` Interface

type HSTokenOptions

type HSTokenOptions func(*hsTokenFn) *hsTokenFn

HSTokenOptions provides the functional options for the GetHSToken function

func HSTokenDuration

func HSTokenDuration(d time.Duration) HSTokenOptions

HSTokenDuration functional option sets the Duration after which the token expires

func HSTokenExpiry

func HSTokenExpiry(ex time.Time) HSTokenOptions

HSTokenExpiry functional option sets the Exact Expiry time of the token

func HSTokenWith

func HSTokenWith(ID, audience, issuer, subject string) HSTokenOptions

HSTokenWith functional option sets the additional parameters in the JWT token

type Pbkdf2Options

type Pbkdf2Options func(*pbkdf2Fn) *pbkdf2Fn

Pbkdf2Options type provides a way to create functional options for PBKDF2

func Pbkdf2Salt

func Pbkdf2Salt(buf []byte) Pbkdf2Options

Pbkdf2Salt sets a fixed salt for PBKDF2 Key derivation

func Pbkdf2With

func Pbkdf2With(rounds, size int) Pbkdf2Options

Pbkdf2With sets the number of rounds and output size of the PBKDF2