argon2

package module
v0.0.0-...-49d0f0e Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2018 License: MIT Imports: 7 Imported by: 1

README

go-argon2

GoDoc

Go bindings for the reference C implementation of Argon2, the winner of the Password Hash Competition.

Installation

$ go get -d github.com/tvdburgt/go-argon2

This package depends on libargon2, specifically libargon2.so and argon2.h. Make sure the library files are available in /usr:

$ git clone https://github.com/P-H-C/phc-winner-argon2.git argon2
$ cd argon2
$ git checkout tags/20171227 # switch to latest release
$ sudo make install

Test everything is installed correctly:

$ cd $GOPATH/src/github.com/tvdburgt/go-argon2/
$ go test

Usage

Raw hash with default configuration
hash, err := argon2.Hash(argon2.NewContext(), []byte("password"), []byte("somesalt"))
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%x\n", hash)
Encoded hash with custom configuration
ctx := &argon2.Context{
	Iterations:  5,
	Memory:      1 << 16,
	Parallelism: 2,
	HashLen:     32,
	Mode:        argon2.ModeArgon2i,
	Version:     argon2.Version13,
}

s, err := argon2.HashEncoded(ctx, []byte("password"), []byte("somesalt"))
if err != nil {
	log.Fatal(err)
}

fmt.Println(s)

Documentation

Overview

Package argon2 provides low-level bindings for the Argon2 hashing library: libargon2. Argon2 specifies three versions: Argon2i, Argon2d, and Argon2id. Argon2i is useful for protection against side-channel attacks (key derivation), while Argon2d provides the highest resistance against GPU cracking attacks (proof-of-work). Argon2id provides good protection against both side-channel and GPU cracking attacks.

Index

Examples

Constants

View Source 
const (
	ModeArgon2d  int = C.Argon2_d
	ModeArgon2i  int = C.Argon2_i
	ModeArgon2id int = C.Argon2_id
)
View Source 
const (
	Version10      int = C.ARGON2_VERSION_10
	Version13      int = C.ARGON2_VERSION_13
	VersionDefault int = C.ARGON2_VERSION_NUMBER
)
View Source 
const (
	FlagDefault       int = C.ARGON2_DEFAULT_FLAGS
	FlagClearPassword int = C.ARGON2_FLAG_CLEAR_PASSWORD
	FlagClearSecret   int = C.ARGON2_FLAG_CLEAR_SECRET
)

Variables

View Source 
var (
	ErrContext  = errors.New("argon2: context is nil")
	ErrPassword = errors.New("argon2: password is nil or empty")
	ErrSalt     = errors.New("argon2: salt is nil or empty")
	ErrHash     = errors.New("argon2: hash is nil or empty")
)

Functions

func Hash 

func Hash(ctx *Context, password, salt []byte) ([]byte, error)

Hash hashes a password given a salt and an initialized Argon2 context. It returns the calculated hash as an output of raw bytes.

Example 
password := []byte("password")
salt := make([]byte, 16) // pad salt to 16 bytes
copy(salt, []byte("somesalt"))

ctx := &argon2.Context{
	Iterations:  2,
	Memory:      1 << 16,
	Parallelism: 4,
	HashLen:     32,
	Mode:        argon2.ModeArgon2i,
	Version:     argon2.Version10,
}

hash, err := argon2.Hash(ctx, password, salt)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%x\n", hash)

Output:

4162f32384d8f4790bd994cb73c83a4a29f076165ec18af3cfdcf10a8d1b9066

func HashEncoded 

func HashEncoded(ctx *Context, password []byte, salt []byte) (string, error)

HashEncoded hashes a password and produces a crypt-like encoded string.

Example 
password := []byte("password")
salt := make([]byte, 16) // pad salt to 16 bytes
copy(salt, []byte("somesalt"))

ctx := &argon2.Context{
	Iterations:  2,
	Memory:      1 << 16,
	Parallelism: 4,
	HashLen:     32,
	Mode:        argon2.ModeArgon2i,
	Version:     argon2.Version10,
}

s, err := argon2.HashEncoded(ctx, password, salt)
if err != nil {
	log.Fatal(err)
}

fmt.Println(s)

Output:

$argon2i$v=16$m=65536,t=2,p=4$c29tZXNhbHQAAAAAAAAAAA$QWLzI4TY9HkL2ZTLc8g6SinwdhZewYrzz9zxCo0bkGY

func Verify 

func Verify(ctx *Context, hash, password, salt []byte) (bool, error)

Verify verifies an Argon2 hash against a plaintext password.

func VerifyEncoded 

func VerifyEncoded(s string, password []byte) (bool, error)

VerifyEncoded verifies an encoded Argon2 hash s against a plaintext password.

Types

type Context 

type Context struct {
	Iterations     int    // number of iterations (t_cost)
	Memory         int    // memory usage in KiB (m_cost)
	Parallelism    int    // number of parallel threads
	HashLen        int    // desired hash output length
	Mode           int    // ModeArgon2d, ModeArgon2i, or ModeArgon2id
	Version        int    // Version10 or Version13 (aka VersionDefault)
	Secret         []byte // optional (not used by default)
	AssociatedData []byte // optional (not used by default)
	Flags          int    // optional (default is FlagDefault)
}

Context represents a structure that holds all static configuration values, used to parameterize an Argon2 hash function.

func NewContext 

func NewContext(mode ...int) *Context

NewContext initializes a new Argon2 context with reasonable defaults. allows the mode to be set as an optional paramter

type Error 

type Error int

Error represents the internal error code propagated from libargon2. 

var (
	ErrOutputPtrNull         Error = C.ARGON2_OUTPUT_PTR_NULL
	ErrOutputTooShort        Error = C.ARGON2_OUTPUT_TOO_SHORT
	ErrOutputTooLong         Error = C.ARGON2_OUTPUT_TOO_LONG
	ErrPwdTooShort           Error = C.ARGON2_PWD_TOO_SHORT
	ErrPwdTooLong            Error = C.ARGON2_PWD_TOO_LONG
	ErrSaltTooShort          Error = C.ARGON2_SALT_TOO_SHORT
	ErrSaltTooLong           Error = C.ARGON2_SALT_TOO_LONG
	ErrAdTooShort            Error = C.ARGON2_AD_TOO_SHORT
	ErrAdTooLong             Error = C.ARGON2_AD_TOO_LONG
	ErrSecretTooShort        Error = C.ARGON2_SECRET_TOO_SHORT
	ErrSecretTooLong         Error = C.ARGON2_SECRET_TOO_LONG
	ErrTimeTooSmall          Error = C.ARGON2_TIME_TOO_SMALL
	ErrTimeTooLarge          Error = C.ARGON2_TIME_TOO_LARGE
	ErrMemoryTooLittle       Error = C.ARGON2_MEMORY_TOO_LITTLE
	ErrMemoryTooMuch         Error = C.ARGON2_MEMORY_TOO_MUCH
	ErrLanesTooFew           Error = C.ARGON2_LANES_TOO_FEW
	ErrLanesTooMany          Error = C.ARGON2_LANES_TOO_MANY
	ErrPwdPtrMismatch        Error = C.ARGON2_PWD_PTR_MISMATCH
	ErrSaltPtrMismatch       Error = C.ARGON2_SALT_PTR_MISMATCH
	ErrSecretPtrMismatch     Error = C.ARGON2_SECRET_PTR_MISMATCH
	ErrAdPtrMismatch         Error = C.ARGON2_AD_PTR_MISMATCH
	ErrMemoryAllocationError Error = C.ARGON2_MEMORY_ALLOCATION_ERROR
	ErrFreeMemoryCbkNull     Error = C.ARGON2_FREE_MEMORY_CBK_NULL
	ErrAllocateMemoryCbkNull Error = C.ARGON2_ALLOCATE_MEMORY_CBK_NULL
	ErrIncorrectParameter    Error = C.ARGON2_INCORRECT_PARAMETER
	ErrIncorrectType         Error = C.ARGON2_INCORRECT_TYPE
	ErrOutPtrMismatch        Error = C.ARGON2_OUT_PTR_MISMATCH
	ErrThreadsTooFew         Error = C.ARGON2_THREADS_TOO_FEW
	ErrThreadsTooMany        Error = C.ARGON2_THREADS_TOO_MANY
	ErrMissingArgs           Error = C.ARGON2_MISSING_ARGS
	ErrEncodingFail          Error = C.ARGON2_ENCODING_FAIL
	ErrDecodingFail          Error = C.ARGON2_DECODING_FAIL
	ErrThreadFail            Error = C.ARGON2_THREAD_FAIL
	ErrDecodingLengthFail    Error = C.ARGON2_DECODING_LENGTH_FAIL
	ErrVerifyMismatch        Error = C.ARGON2_VERIFY_MISMATCH
)

func (Error) Error 

func (e Error) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.