gophc

README

gophc

A library to parse and create P-H-C strings.

The PHC string format defines a "standard" for string encodings for the output of a password hashing function.

gophc is a pure Go implementation of this standard.

Disclaimer: No warranty or anything that it implements the standard 100%!

WARNING: UNDER CONSTRUCTION

Documentation

Index

• Variables
• func Base64Decode(src []byte) ([]byte, error)
• func Base64DecodeNotStrict(src []byte) ([]byte, error)
• func Base64Encode(src []byte) []byte
• func DecodeDecimalString(s string, strict bool, bitSize int) (int64, error)
• func DecodeUnsignedString(s string, strict bool, bitSize int) (uint64, error)
• func NewMismatchedFunctionNameError(gotName string, expectedNames ...string) error
• func NoValueValidator(value string) error
• func ValueCharacterValidator(value string) error
• type Argon2PHC
  • func DecodeArgon2(phcString string) (*Argon2PHC, error)
  • func (phc *Argon2PHC) ValidateParameters() error
• type Base64Decoder
• type Base64Encoder
• type DefaultBase64Handler
  • func NewDefaultBase64Handler(strict bool) DefaultBase64Handler
  • func (h DefaultBase64Handler) Base64Decode(src []byte) ([]byte, error)
  • func (h DefaultBase64Handler) Base64Encode(src []byte) []byte
• type PHCError
  • func NewPHCError(message string, wrapped error) *PHCError
  • func (err *PHCError) Error() string
  • func (err *PHCError) Unwrap() error
• type PHCInstance
• type PHCParameterDescription
  • func (description *PHCParameterDescription) GetValueValidatorFunc() ValueValidatorFunc
• type PHCParser
  • func NewPHCParser() *PHCParser
  • func (parser *PHCParser) Parse(s string) (PHCInstance, error)
• type PHCSchema
  • func (schema *PHCSchema) Decode(s string) (PHCInstance, error)
• type ParameterValuePair
• type ScryptPHC
  • func DecodeScrypt(phcString string) (*ScryptPHC, error)
  • func (phc *ScryptPHC) ValidateParameters() error
• type ValueValidatorFunc

Variables

var (
	ErrNonOptionalParameterMissing = errors.New("non optional parameter is missing")
	ErrParameterValueValidation    = errors.New("validation of parameter failed")
	ErrMismatchedFunctionName      = errors.New("invalid function name")
	ErrUnmatchedParameterName      = errors.New("unmatched parameter parsed")
)

var (
	ErrInvalidPHCStructure   = errors.New("invalid phc syntax")
	ErrInvalidFunctionName   = errors.New("invalid function name")
	ErrInvalidParameterName  = errors.New("invalid parameter name")
	ErrInvalidParameterValue = errors.New("invalid parameter value")
	ErrMissingParameterValue = errors.New("no value for parameter given")
	ErrBase64Decode          = errors.New("error decoding base64")
)

var Argon2Schema = &PHCSchema{
	FunctionNames: Argon2Variants,
	ParameterDescriptions: []*PHCParameterDescription{
		{
			Name:          "v",
			Default:       strconv.FormatUint(uint64(defaultArgon2Version), 10),
			Optional:      true,
			ValidateValue: NoValueValidator,
		},
		{
			Name:          "m",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
		{
			Name:          "t",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
		{
			Name:          "p",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
	},
	Decoder: DefaultBase64,
}

var Argon2Variants = []string{
	"argon2id",
	"argon2i",
	"argon2d",
}

var Argon2Versions = []uint32{
	0x10,
	0x13,
}

var DefaultBase64 = NewDefaultBase64Handler(true)

var (
	ErrInvalidArgon2Version = errors.New("invalid argon2 version")
)

var (
	NonMinimalDecimalEncoding = errors.New("not the minimal decimal encoding")
)

var ScryptPHCSchema = &PHCSchema{
	FunctionNames: []string{"scrypt"},
	ParameterDescriptions: []*PHCParameterDescription{
		{
			Name:          "ln",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
		{
			Name:          "r",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
		{
			Name:          "p",
			Default:       "",
			Optional:      false,
			ValidateValue: NoValueValidator,
		},
	},
	Decoder: DefaultBase64,
}

Functions

func Base64Decode

func Base64Decode(src []byte) ([]byte, error)

Base64Decode decodes the source using the alphabet.

func Base64DecodeNotStrict

func Base64DecodeNotStrict(src []byte) ([]byte, error)

Base64DecodeNotStrict decodes the source using the alphabet.

In contrast to Base64Decode this method also allows non-zero trailing padding bits.

func Base64Encode

func Base64Encode(src []byte) []byte

Base64Encode encodes the source to base64 using the alphabet.

func DecodeDecimalString

func DecodeDecimalString(s string, strict bool, bitSize int) (int64, error)

func DecodeUnsignedString

func DecodeUnsignedString(s string, strict bool, bitSize int) (uint64, error)

func NewMismatchedFunctionNameError

func NewMismatchedFunctionNameError(gotName string, expectedNames ...string) error

func NoValueValidator

func NoValueValidator(value string) error

func ValueCharacterValidator

func ValueCharacterValidator(value string) error

Types

type Argon2PHC

type Argon2PHC struct {
	Variant string
	Version uint32
	M       uint32
	T       uint32
	P       uint8
}

func DecodeArgon2

func DecodeArgon2(phcString string) (*Argon2PHC, error)

func (*Argon2PHC) ValidateParameters

func (phc *Argon2PHC) ValidateParameters() error

type Base64Decoder

type Base64Decoder interface {
	Base64Decode(src []byte) ([]byte, error)
}

type Base64Encoder

type Base64Encoder interface {
	Base64Encode(src []byte) []byte
}

type DefaultBase64Handler

type DefaultBase64Handler struct {
	Strict bool
}

func NewDefaultBase64Handler

func NewDefaultBase64Handler(strict bool) DefaultBase64Handler

func (DefaultBase64Handler) Base64Decode

func (h DefaultBase64Handler) Base64Decode(src []byte) ([]byte, error)

func (DefaultBase64Handler) Base64Encode

func (h DefaultBase64Handler) Base64Encode(src []byte) []byte

type PHCError

type PHCError struct {
	Message    string
	WrappedErr error
}

func NewPHCError

func NewPHCError(message string, wrapped error) *PHCError

func (*PHCError) Error

func (err *PHCError) Error() string

func (*PHCError) Unwrap

func (err *PHCError) Unwrap() error

type PHCInstance

type PHCInstance struct {
	Function   string
	Parameters []ParameterValuePair
	Salt       []byte
	SaltString string
	Hash       []byte
	HashString string
}

type PHCParameterDescription

type PHCParameterDescription struct {
	Name          string
	Default       string
	Optional      bool
	ValidateValue ValueValidatorFunc
}

func (*PHCParameterDescription) GetValueValidatorFunc

func (description *PHCParameterDescription) GetValueValidatorFunc() ValueValidatorFunc

type PHCParser

type PHCParser struct {
	MinFunctionNameLength, MaxFunctionNameLength     int
	MinParameterNameLength, MaxParameterNameLength   int
	MinParameterValueLength, MaxParameterValueLength int
	Decoder                                          Base64Decoder
}

func NewPHCParser

func NewPHCParser() *PHCParser

func (*PHCParser) Parse

func (parser *PHCParser) Parse(s string) (PHCInstance, error)

type PHCSchema

type PHCSchema struct {
	FunctionNames         []string
	ParameterDescriptions []*PHCParameterDescription
	Decoder               Base64Decoder
}

func (*PHCSchema) Decode

func (schema *PHCSchema) Decode(s string) (PHCInstance, error)

type ParameterValuePair

type ParameterValuePair struct {
	Name  string
	Value string
	IsSet bool
}

type ScryptPHC

type ScryptPHC struct {
	// The cost parameter N
	Cost int
	// Block size parameter r
	BlockSize int
	// The parallelism parameter p
	Parallelism int
	Salt        []byte
	SaltString  string
	Hash        []byte
	HashString  string
}

func DecodeScrypt

func DecodeScrypt(phcString string) (*ScryptPHC, error)

func (*ScryptPHC) ValidateParameters

func (phc *ScryptPHC) ValidateParameters() error

type ValueValidatorFunc

type ValueValidatorFunc func(value string) error