pwdatav3

README

pwdatav3

-- import "github.com/forsyth/pwdatav3"

Package pwdatav3 provides password hashing and verification compatible with ASP.NET Core applications. It helped migrate applications from C# to Go, without requiring users to re-register or reset their passwords. Separately, package aspnetusers supports compatible sharing of the same authentication database. The two are now separate packages because the Go application might just as well use its own user registration scheme, while keeping the same password encoding (so users do not need to re-register).

Documentation

Overview

Package pwdatav3 implements password hashing and verification compatible with Microsoft's ASP.NET Core, including equality of the hashed salted passwords. It is useful when switching from C# to Go for the server side of an application, avoiding the need to reset passwords when switching.

The type PWHash provides compatible hashing and verify functions.

Index

• Constants
• Variables
• func CompareHashAndPassword(hashedPassword, password []byte) error
• func DecodeString(s string) ([]byte, error)
• func EncodeToString(hashedPassword []byte) string
• func GenerateFromPassword(password []byte, iter int) ([]byte, error)
• type PWHash
  • func New(pw string, iter int) (*PWHash, error)
  • func (pd *PWHash) MarshalBinary() ([]byte, error)
  • func (pd *PWHash) MarshalText() ([]byte, error)
  • func (pd *PWHash) String() string
  • func (pd *PWHash) UnmarshalBinary(a []byte) error
  • func (pd *PWHash) UnmarshalText(text []byte) error
  • func (pd *PWHash) Verify(pw string) bool

Constants

const (

	// Default hash iterations used by ASP.NET.
	DefaultIter = 10000

	// Default salt length used by ASP.NET.
	DefaultSaltLen = 16
)

Variables

var (
	// errors returned for a corrupt base64 representation.
	ErrCorrupt                   = errors.New("malformed hashed value")
	ErrVersion                   = errors.New("unknown hashed format version")
	ErrFunction                  = errors.New("unknown hash function")
	ErrParameter                 = errors.New("invalid hash function parameter")
	ErrMismatchedHashAndPassword = errors.New("pwdatav3: hashedPassword is not the hash of the given password")
)

Functions

func CompareHashAndPassword

func CompareHashAndPassword(hashedPassword, password []byte) error

CompareHashAndPassword(compares a hashed password in its binary representation, as produced by GenerateFromPassword, with its possible plaintext equivalent, returning nil on success or an error on failure.

func DecodeString

func DecodeString(s string) ([]byte, error)

DecodeString returns the hashed password given its base64 representation as produced by EncodeToString.

func EncodeToString

func EncodeToString(hashedPassword []byte) string

EncodeToString returns a base64 form of the hashed password compatible with ASP.NET's password-file format, but also usable elsewhere.

func GenerateFromPassword

func GenerateFromPassword(password []byte, iter int) ([]byte, error)

GemerateFromPassword returns the hash of the password with the given iterations, as a binary encoding. (DefaultIter is the iteration count compatible with ASP.NET.) Use CompareHashAndPassword, defined in this package, to compare the returned hashed password with its cleartext version. The only possible error is a failure to make a random salt.

Types

type PWHash

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

PWHash represents a hashed value (version 3 for ASP.NET) using PBKDF2 with HMAC-SHA256, and by default, 128-bit salt, 256-bit hash and 10000 iterations.

func New

func New(pw string, iter int) (*PWHash, error)

New returns a hashed value for the given password and iterations. DefaultIter is an ASP.NET-compatible choice, using a random salt that is DefaultSaltLen bytes long. It returns nil and an error only if it cannot make a random salt, which suggests trouble with the underlying random number source.

func (*PWHash) MarshalBinary

func (pd *PWHash) MarshalBinary() ([]byte, error)

MarshalBinary returns a binary representation of a hashed value that is identical to ASP.NET's:

ver[1]=0x01, prf[4]=0x01, iter[4], saltLen[4], salt[n], hashed[sha256.Size]

(All 32-bit ints are stored big-endian.) No error can result.

func (*PWHash) MarshalText

func (pd *PWHash) MarshalText() ([]byte, error)

MarshalText returns the hashed value encoded as required for ASP.NET's user table. No error can result.

func (*PWHash) String

func (pd *PWHash) String() string

String returns the Base64 encoding.

func (*PWHash) UnmarshalBinary

func (pd *PWHash) UnmarshalBinary(a []byte) error

UnmarshalBinary extracts the components from a packed value. Various errors can be returned if the format is wrong or uses unsupported parameters. The pd value is unchanged on error.

func (*PWHash) UnmarshalText

func (pd *PWHash) UnmarshalText(text []byte) error

UnmarshalText unmarshals a hashed value decoded from text, typically the value stored in a user table record.

func (*PWHash) Verify

func (pd *PWHash) Verify(pw string) bool

Verify returns true iff the given plaintext password corresponds to the value hashed in pd.