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).
Variant	Variant	argon2.ID	Argon2 variant to be used (argon2.ID or argon2.I)
KeyLen	int	64	How many bytes to generate as output.
SaltLen	int	16	Salt length in bytes

Usage with PHC Crypto

package main

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

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

	hash, err := phccrypto.Hash("password")
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(hash) // $argon2id$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

package main

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

func main() {
	hash, err := argon2.Hash("password", argon2.Config{
		Parallelism: 3,
		Variant:     argon2.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
• Variables
• func Hash(plain string, config Config) (string, error)
• func Verify(hash string, plain string) (bool, error)
• type Config
• type Variant

Constants

const (
	// KEY_LENGTH is the desired number of returned bytes
	KEY_LENGTH = 64
	// TIME is the number of iterations to perform
	TIME = 16
	// MEMORY is the a mount of memory (in kilobytes) to use
	MEMORY = 64 * 1024
	// PARALLELISM is the degree of parallelism (i.e. number of threads)
	PARALLELISM = 4
	// DEFAULT_VARIANT combines the Argon2d and Argon2i
	DEFAULT_VARIANT = ID
	// SALT_LENGTH is the default salth length in bytes.
	SALT_LENGTH = 32
)

Variables

var ErrEmptyField error = errors.New("function parameters must not be empty")

Functions

func Hash

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

Hash creates a PHC-formatted hash with config provided

package main

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

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

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.

package main

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

func main() {
  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
}

Types

type Config

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

Config initialize the config require to create a hash function

type Variant

type Variant int

Variant sets up enum for available Argon2 variants

const (
	// ID points to Argon2 id variant
	ID Variant = iota
	// I points to Argon2 i variant
	I
)