argonpass

package module
Version: v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 11, 2020 License: MIT Imports: 10 Imported by: 1

README

goArgonPass

GoDoc codecov Go Report Card CodeFactor

Travis:

Travis Build Status

Drone:

Drone Build Status

All hashing and crypto is done by Go library packages. This is only a utility package to make the process described easier.

Description

goArgonPass is a Argon2 Password utility package for Go using the crypto library package Argon2. Argon2 was the winner of the most recent Password Hashing Competition and doesn't suffer from issues that Bcrypt has such as truncating input over 72 characters. This is designed for use anywhere password hashing and verification might be needed and is intended to replace implementations using bcrypt or Scrypt. The string input/output format was designed to be compatible with Passlib for Python and Argon2 PHP, and you should have full compatibility using the argon2i function, but will not be able to use argon2id, which is the default for this pacakge until those libraries are updated to support it. I encourage you to find the parameters that work best for your application, but the defaults are resonable for an interactive use such as a web application login.

The default Argon2 function is Argon2id, which is a hybrid version of Argon2 combining Argon2i and Argon2d. Argon2id is side-channel resistant and provides better brute- force cost savings due to time-memory tradeoffs than Argon2i, but Argon2i is still plenty secure.

IETF Recommendation is:

Argon2id variant with t=1 and maximum available memory is recommended as a default setting for all environments. This setting is secure against side-channel attacks and maximizes adversarial costs on dedicated bruteforce hardware.

Get Started

go get github.com/dwin/goArgonPass

See example/example.go:

import (
    "fmt"
    "os"

    argonpass "github.com/dwin/goArgonPass"
)

func main() {
    // Obtain user password from form or other input
    userPassInput := "password"

    // Hash with Default Parameters
    hash, err := argonpass.Hash(userPassInput, nil)
    if err != nil {
        // Handle Error
        os.Exit(1)
    }
    fmt.Println("Hash Output: ", hash)
    // Verify Hash
    err = argonpass.Verify(userPassInput, hash)
    if err != nil {
        fmt.Println("Hash verification error: ", err)
    }
    fmt.Println("Hash verified")
}

Output Format
$ argon2id$v=19$m=65536,t=1,p=4$in2Oi1x57p0=$FopwSR12aLJ9OGPw1rKU5K5osAOGxOJzxC/shk+i850=

$ argon2{function(i/id)}$v={version}$m={memory},t={time},p={parallelism}${salt(base64)}${digest(base64)}
Other Notes
Custom Parameters

Set Custom Parameters by passing ArgonParams{} to Hash().

Parameter Type Default Valid Range
Time uint32 1 >= 1
Memory uint32 65536 >= 1024
Parallelism uint8 4 1-64
OutputSize uint32 16 16-64
Function ArgonVariant ArgonVariant2id ArgonVariant2id - ArgonVariant2i
SaltSize uint8 16 16-64
type ArgonParams struct {
    Time        uint32
    Memory      uint32
    Parallelism uint8
    OutputSize  uint32
    Function    ArgonVariant
    SaltSize    uint8
}

Documentation

Overview

Package argonpass provides passphrase hashing and hash verification using the Argon2 password hashing method.

The default Argon2 function is “`Argon2id“`, which is a hybrid version of Argon2 combining Argon2i and Argon2d. Argon2id is side-channel resistant and provides better brute- force cost savings due to time-memory tradeoffs than Argon2i, but Argon2i is still plenty secure.

The string input/output format was designed to be compatible with [Passlib for Python](https://passlib.readthedocs.io/en/stable/lib/passlib.hash.argon2.html) and [Argon2 PHP](https://wiki.php.net/rfc/argon2_password_hash), and you should have full compatibility using the “`argon2i“` function, but will not be able to use “`argon2id“`, which is the default for this package until those libraries are updated to support it. I encourage you to find the parameters that work best for your application, but the defaults are resonable for an interactive use such as a web application login.

Index

Constants

View Source
const (
	Sec128b = 128 >> 3 // Until year 2022
	Sec192b = 192 >> 3
	Sec224b = 224 >> 3
	Sec256b = 256 >> 3
	Sec384b = 384 >> 3
	Sec512b = 512 >> 3
)

Security levels from bits.

View Source
const (
	// DefaultMemory ...
	DefaultMemory = 64 * 1024
	// DefaultParallelism ...
	DefaultParallelism = 4
	// DefaultOutputSize ...
	DefaultOutputSize = Sec128b
	// DefaultFunction ...
	DefaultFunction = ArgonVariant2id
	// DefaultSaltSize ...
	DefaultSaltSize = Sec128b
	// DefaultTime ...
	DefaultTime = 1
)

Variables

View Source
var (
	// ErrPassphraseInputTooShort indicates the passphrase was less than 8 characters.
	ErrPassphraseInputTooShort = errors.New("passphrase input too short, must be >= 8 characters")

	// ErrVersion indicates the version could not be found in hash string or version of hash is
	// greater than current package version and is incompatible.
	ErrVersion = errors.New("unable to parse version or incorrect version")

	// ErrFunctionMismatch indicates the function does not match a supported Argon2 function of 'i' or 'id'.
	ErrFunctionMismatch = errors.New("function of hash is invalid, must be 'argon2i' or 'argon2id'")

	// ErrDecodingSalt indicates there was an issue converting the expected base64 salt to bytes.
	ErrDecodingSalt = errors.New("unable to decode salt base64 to byte")

	// ErrDecodingDigest indicates there was an issue converting the expected base64 hash digest to bytes.
	ErrDecodingDigest = errors.New("unable to decode passhash digest base64 to byte")

	// ErrParseTime indicates there was an issue parsing the time parameter from the hash
	// input string, possibly was not expected integer value.
	ErrParseTime = errors.New("unable to parse time parameter or invalid integer for bitsize")

	// ErrParseMemory indicates there was an issue parsing the memory parameter from the hash
	// input string, possibly was not expected integer value.
	ErrParseMemory = errors.New("unable to parse memory parameter or invalid integer for bitsize")

	// ErrParseParallelism indicates there was an issue parsing the parallelism parameter from the hash
	// input string, possibly was not expected integer value.
	ErrParseParallelism = errors.New("unable to parse parallelism/threads parameter or invalid integer for bitsize")

	// ErrHashMismatch indicates the Argon2 digest regenerated using the hash input string salt
	// and user password input did not produce a matching value. Passphrase input does not match
	// hash string input.
	ErrHashMismatch = errors.New("unable to verify passphrase input with given hash value")

	// ErrInvalidHashFormat indicates the hash string input does not match specified format,
	// example: '$argon2{function(i/id)}$v={version}$m={memory},t={time},p={parallelism}${salt(base64)}${digest(base64)}'.
	ErrInvalidHashFormat = errors.New("invalid hash input string format")
)

Functions

func Benchmark

func Benchmark(params *ArgonParams) (elapsed float64, err error)

Benchmark takes ArgonParams and returns the number of seconds elapsed as a float64 and error.

func Hash

func Hash(pass string, customParams *ArgonParams) (string, error)

Hash generates a argon2id hash of the input pass string and returns the output in the specified string format and error value. Whether 'ArgonParams' is null, then it used default settings.

func Verify

func Verify(pass, hash string) error

Verify regenerates the hash using the supplied pass and compares the value returning an error if the password is invalid or another error occurs. Any error should be considered a validation failure.

Types

type ArgonParams

type ArgonParams struct {
	Function    ArgonVariant
	Time        uint32
	Memory      uint32
	OutputSize  uint32
	Parallelism uint8
	SaltSize    uint8
}

ArgonParams control how the Argon2 function creates the digest output.

func GetParams

func GetParams(hash string) (hashParams *ArgonParams, err error)

GetParams takes hash sting as input and returns parameters as ArgonParams along with error.

func NewDefaultParams added in v1.2.1

func NewDefaultParams() *ArgonParams

NewDefaultParams returns the parameters used by default.

type ArgonVariant added in v1.2.1

type ArgonVariant string

ArgonVariant describes an Argon2 hashing variant.

const (
	// ArgonVariant2i describe the Argon2i variant.
	ArgonVariant2i ArgonVariant = "argon2i"
	// ArgonVariant2id describe the Argon2id variant.
	ArgonVariant2id ArgonVariant = "argon2id"
)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL