makwa

README

makwa

A pure Go implementation of the Makwa password hashing algorithm.

For documentation, check godoc.

Documentation

Overview

Package makwa implements the Makwa password hashing algorithm.

Makwa is a candidate in the Password Hashing Competition which uses squaring modulo Blum integers to provide a one-way function with number-theoretic security.

https://password-hashing.net/submissions/specs/Makwa-v0.pdf

Index

• Variables
• func CheckPassword(params PublicParameters, digest *Digest, password []byte) error
• func Extend(params PublicParameters, digest *Digest, workFactor int) error
• func Recover(params PrivateParameters, digest *Digest) ([]byte, error)
• type Digest
  • func Hash(params PublicParameters, password, salt []byte, workFactor int, preHash bool, ...) (*Digest, error)
  • func (d *Digest) MarshalText() ([]byte, error)
  • func (d *Digest) String() string
  • func (d *Digest) UnmarshalText(text []byte) error
• type PrivateParameters
  • func GenerateParameters(bits int) (*PrivateParameters, error)
• type PublicParameters
  • func (p PublicParameters) ModulusID() []byte

Variables

var ErrBadBase64 = errors.New("bad base64")

ErrBadBase64 is returned when the provided Base64 value cannot be decoded.

var ErrBadPassword = errors.New("bad password")

ErrBadPassword is returned when a bad password is provided.

var ErrInvalidWorkFactor = errors.New("invalid work factor")

ErrInvalidWorkFactor is returned when the given work factor cannot be encoded as a power of 2 or 3.

var ErrWrongParams = errors.New("wrong parameters")

ErrWrongParams is returned when a password is being checked using the wrong parameters.

Functions

func CheckPassword

func CheckPassword(params PublicParameters, digest *Digest, password []byte) error

CheckPassword safely compares a password to a digest of a password.

func Extend

func Extend(params PublicParameters, digest *Digest, workFactor int) error

Extend re-hashes the given digest to increase its work factor.

func Recover

func Recover(params PrivateParameters, digest *Digest) ([]byte, error)

Recover uses the private parameters to recover the plaintext of a password digest.

Types

type Digest

type Digest struct {
	ModulusID   []byte
	Hash        []byte
	Salt        []byte
	WorkFactor  int
	PreHash     bool
	PostHashLen int
}

A Digest is a hashed password.

func Hash

func Hash(params PublicParameters, password, salt []byte, workFactor int, preHash bool, postHashLen int) (*Digest, error)

Hash returns a digest of the given password using the given parameters. If the given salt is nil, generates a random salt of sufficient length.

func (*Digest) MarshalText

func (d *Digest) MarshalText() ([]byte, error)

MarshalText marshals a digest into a text format.

func (*Digest) String

func (d *Digest) String() string

func (*Digest) UnmarshalText

func (d *Digest) UnmarshalText(text []byte) error

UnmarshalText unmarshals a digest from a text format.

type PrivateParameters

type PrivateParameters struct {
	PublicParameters
	P, Q *big.Int
}

PrivateParameters are the private parameters associated with Makwa.

func GenerateParameters

func GenerateParameters(bits int) (*PrivateParameters, error)

GenerateParameters generates a random Makwa modulus of the given size.

type PublicParameters

type PublicParameters struct {
	N    *big.Int
	Hash func() hash.Hash
}

PublicParameters are the public parameters associated with Makwa.

func (PublicParameters) ModulusID

func (p PublicParameters) ModulusID() []byte

ModulusID returns a fingerprint of the modulus.