argon2

README

PHC Crypto - Argon2

According to Wikipedia:

Argon2 is a key derivation function that was selected as the winner of the Password Hashing Competition in July 2015. It was designed by Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich from the University of Luxembourg. The reference implementation of Argon2 is released under a Creative Commons CC0 license (i.e. public domain) or the Apache License 2.0, and provides three related versions:

• Argon2d maximizes resistance to GPU cracking attacks. It accesses the memory array in a password dependent order, which reduces the possibility of time–memory trade-off (TMTO) attacks, but introduces possible side-channel attacks.
• Argon2i is optimized to resist side-channel attacks. It accesses the memory array in a password independent order.
• Argon2id is a hybrid version. It follows the Argon2i approach for the first half pass over memory and the Argon2d approach for subsequent passes. The Internet draft recommends using Argon2id except when there are reasons to prefer one of the other two modes.

All three modes allow specification by three parameters that control:

• execution time
• memory required
• degree of parallelism

Configuration options

Key	Type	Default	Notes
Time	int	32768	Number of iterations to perform
Memory	int	8	Amount of memory (in kilobytes) to use
Parallelism	int	4	Parallelism factor (threads to run in parallel).
KeyLen	int	64	How many bytes to generate as output.
Variant	string	id	Argon2 variant to be used (id or i)

Usage with PHC Crypto

$ go get github.com/aldy505/phc-crypto

import (
  "fmt"
  "github.com/aldy505/phc-crypto"
)

func main() {
  crypto, err := phccrypto.Use("argon2", phccrypto.Config{
    Parallelism: 3,
    Variant: "i",
  })
  if err != nil {
    fmt.Println(err)
  }

  hash, err := phccrypto.Hash("password")
  if err != nil {
    fmt.Println(err)
  }
  fmt.Println(hash) // $argon2i$v=19$m=65536,t=16,p=3$8400b4e5f01f30092b794de34c61a6fdfea6b6b446560fda08a876bd11e9c62e$3fd77927d189...

  verify, err := phccrypto.Verify(hash, "password")
  if err != nil {
    fmt.Println(err)
  }
  fmt.Println(verify) // true
}

Standalone usage

$ go get github.com/aldy505/phc-crypto/argon2

import (
  "fmt"
  "github.com/aldy505/phc-crypto/argon2"
)

func main() {

  hash, err := argon2.Hash("password", argon2.Config{
    Parallelism: 3,
    Variant: "i",
  })
  if err != nil {
    fmt.Println(err)
  }
  fmt.Println(hash) // $argon2i$v=19$m=65536,t=16,p=3$8400b4e5f01f30092b794de34c61a6fdfea6b6b446560fda08a876bd11e9c62e$3fd77927d189...

  verify, err := argon2.Verify(hash, "password")
  if err != nil {
    fmt.Println(err)
  }
  fmt.Println(verify) // true
}

Documentation

Index

• Constants
• func Hash(plain string, config Config) (string, error)
• func Verify(hash string, plain string) (bool, error)
• type Config

Constants

const (
	// Desired number of returned bytes
	KEYLEN = 64
	// Number of iterations to perform
	TIME = 16
	// Amount of memory (in kilobytes) to use
	MEMORY = 64 * 1024
	// Degree of parallelism (i.e. number of threads)
	PARALLELISM = 4
	// Combines the Argon2d and Argon2i
	DEFAULT_VARIANT = "id"
)

Functions

func Hash

func Hash(plain string, config Config) (string, error)

Hash creates a PHC-formatted hash with config provided

func Verify

func Verify(hash string, plain string) (bool, error)

Verify checks the hash if it's equal (by an algorithm) to plain text provided.

Types

type Config

type Config struct {
	Time        int
	Memory      int
	Parallelism int
	KeyLen      int
	Variant     string
}

Config initialize the config require to create a hash function