argon2

package module
v2.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2018 License: MIT Imports: 9 Imported by: 6

README

argon2

The fastest and easiest to use Argon2 bindings for Go!

Features

  • Zero dependencies
  • Easy to use API, including generation of raw and encoded hashes
  • Up to date & used in production environments
  • Up to 180-200% as fast as golang.org/x/crypto/argon2, allowing you to apply more secure settings while keeping the same latency

Usage

See examples/example.go for a simple introduction and try it out with:

go run examples/example.go

Performance

This library makes use of SSE, SSE2, SSSE3 and XOP, depending on whether they are enabled during compilation. This can be done by adding appropriate gcc optimization flags to the CGO_CFLAGS environment variable.

Here's an example which you could set before running go build etc.:

export CGO_CFLAGS="-O3 -march=native"

In this example -march=native will optimize the program for the current platform you're compiling on. If you're planning to deploy this library in a different environment you should replace it with a matching value listed here.

This way you can achieve a significant performance improvement. You can use this performance improvement to apply stronger hash settings and thus improve security at the same cost.

Current downsides

This package uses cgo like all Go bindings and thus comes with all it's downsides. Among others:

  • cgo makes cross-compilation hard
  • Excessive thread spawning¹

¹ Almost every time this library hashes something the scheduler will notice that a Goroutine is blocked in a cgo call and will spawn a new, costly, native thread. To prevent this you may use my workerpool project to set up a worker pool like this.

Modifications to Argon2

Based on fba7b9a.

  • Moved blake2 code into the root source directory and adjusted include paths to match this change.
  • Merged ref.c and opt.c into one file (ref_opt.c). This allows us to use the __SSE__ precompiler flag for SSE detection instead of relying on a Makefile.

Documentation

Overview

Package argon2 provides fast and easy to use bindings for Argon2: A very secure, modern password hashing algorithm - Winner of the Password Hashing Competition (PHC).

Index

Constants

View Source 
const (
	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)
)

Variables

This section is empty.

Functions

func SecureZeroMemory 

func SecureZeroMemory(b []byte)

SecureZeroMemory is a helper method which sets all bytes in `b` (up to it's capacity) to `0x00`, erasing it's contents.

func VerifyEncoded 

func VerifyEncoded(pwd []byte, encoded []byte) (bool, error)

VerifyEncoded returns true if `pwd` matches the encoded hash `encoded` and otherwise false.

Types

type Config 

type Config struct {
	// HashLength specifies the length of the resulting hash in Bytes.
	//
	// Must be > 0.
	HashLength uint32

	// SaltLength specifies the length of the resulting salt in Bytes,
	// if one of the helper methods is used.
	//
	// Must be > 0.
	SaltLength uint32

	// TimeCost specifies the number of iterations of argon2.
	//
	// Must be > 0.
	// If you use ModeArgon2i this should *always* be >= 3 due to TMTO attacks.
	// Additionally if you can afford it you might set it to >= 10.
	TimeCost uint32

	// MemoryCost specifies the amount of memory to use in Kibibytes.
	//
	// Must be > 0.
	MemoryCost uint32

	// Parallelism specifies the amount of threads to use.
	//
	// Must be > 0.
	Parallelism uint32

	// Mode specifies the hashing method used by argon2.
	//
	// If you're writing a server and unsure what to choose,
	// use ModeArgon2i with a TimeCost >= 3.
	Mode Mode

	// Version specifies the argon2 version to be used.
	Version Version
}

Config contains all configuration parameters for the Argon2 hash function.

You MUST ensure that a Config instance is not changed after creation, otherwise you risk race conditions. If you do need to change it during runtime use a Mutex and simply create a by-value copy of your shared Config instance in the critical section and store it on your local stack. That way your critical section is very short, while allowing you to safely call all the member methods on your local "immutable" copy.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a Config struct suitable for most servers.

These default settings follow the recommendation from 

https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03#section-9.4

using ModeArgon2id, TimeCost of 1 and 32 MiB of memory, which result in around 10-15ms of computation time. (Tested on an i7 8700k and DDR4 @ 3200 MHz).

func (*Config) Hash 

func (c *Config) Hash(pwd []byte, salt []byte) (*Raw, error)

Hash takes a password and optionally a salt and returns an Argon2 hash.

If salt is nil a appropriate salt of Config.SaltLength bytes is generated for you.

func (*Config) HashEncoded 

func (c *Config) HashEncoded(pwd []byte) (encoded []byte, err error)

HashEncoded is a helper function around Hash() which automatically generates a salt and encodes the result for you.

func (*Config) HashRaw 

func (c *Config) HashRaw(pwd []byte) (*Raw, error)

HashRaw is a helper function around Hash() which automatically generates a salt for you.

type Error 

type Error C.int

Error represents the error code returned by argon2.

func (Error) Error 

func (e Error) Error() string

type Mode 

type Mode uint32

Mode exists for type check purposes. See Config. 

const (
	// ModeArgon2d is faster and uses data-depending memory access,
	// which makes it highly resistant against GPU cracking attacks and
	// suitable for applications with no (!) threats from
	// side-channel timing attacks (eg. cryptocurrencies).
	ModeArgon2d Mode = C.Argon2_d

	// ModeArgon2i uses data-independent memory access, which is
	// preferred for password hashing and password-based key derivation
	// (e.g. hard drive encryption), but it's slower as it makes
	// more passes over the memory to protect from TMTO attacks.
	ModeArgon2i Mode = C.Argon2_i

	// ModeArgon2id is a hybrid of Argon2i and Argon2d, using a
	// combination of data-depending and data-independent memory accesses,
	// which gives some of Argon2i's resistance to side-channel cache timing
	// attacks and much of Argon2d's resistance to GPU cracking attacks.
	ModeArgon2id Mode = C.Argon2_id
)

func (Mode) String 

func (m Mode) String() string

String simply maps a ModeArgon{d,i,id} constant to a "Argon{d,i,id}" string or returns "unknown" if `m` does not match one of the constants.

type Raw 

type Raw struct {
	Config Config
	Salt   []byte
	Hash   []byte
}

Raw wraps a salt and hash pair including the Config with which it was generated.

A Raw struct is generated using Decode() or the Hash*() methods above. This struct MUST NOT be mutated while any of its member functions are currently being executed.

func Decode 

func Decode(encoded []byte) (*Raw, error)

Decode takes a stringified/encoded argon2 hash and turns it back into a Raw struct.

This decoder ignores "data" attributes as they are likely to be deprecated.

func (*Raw) Encode 

func (raw *Raw) Encode() []byte

Encode turns a Raw struct into the official stringified/encoded argon2 representation.

The resulting byte slice can safely be turned into a string.

func (*Raw) Verify 

func (raw *Raw) Verify(pwd []byte) (bool, error)

Verify returns true if `pwd` matches the hash in `raw` and otherwise false.

type Version 

type Version uint32

Version contains the Argon2 version being used.

See Config. 

const (
	// Version10 of the Argon2 algorithm. Deprecated: Use Version13 instead.
	Version10 Version = C.ARGON2_VERSION_10

	// Version13 of the Argon2 algorithm. Recommended.
	Version13 Version = C.ARGON2_VERSION_13
)

func (Version) String 

func (v Version) String() string

String simply maps a Version{10,13} constant to a "{10,13}" string or returns "unknown" if `v` does not match one of the constants.

Source Files

View all Source files

Directories

Path Synopsis

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.