argon2

README

argon2

Go conversion of the libargon2 library. Exports a simple API with only several features. Unwrapped round function is taken from magical/argon2, licensed under the MIT license.

Please note: due to the nature of the conversion, its performance might be lower than of the bindings. Also the memory clearing is NOT ported and depends on the GC.

Installation

go get github.com/pzduniak/argon2

Performance compared to bindings

Tests were ran on a 2015 Macbook Pro Retina 15". The conversion is ~3.5 times slower.

➜  argon2 git:(master) ✗ go test -bench=.
testing: warning: no tests to run
PASS
BenchmarkBConversion	     100	  14687543 ns/op	 4318704 B/op	     351 allocs/op
BenchmarkBBindings  	     300	   4093711 ns/op	     320 B/op	       3 allocs/op
BenchmarkMConversion	     100	  14622942 ns/op	 4318704 B/op	     351 allocs/op
BenchmarkMMagical   	     100	  14668521 ns/op	 4196464 B/op	       7 allocs/op
ok  	github.com/pzduniak/argon2	6.099s

Usage

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/pzduniak/argon2"
)

func main() {
	var (
		password = []byte("password")
		salt     = []byte("testsalt123")
	)

	output, err := argon2.Key(password, salt, 3, 4, 4096, 32, argon2.Argon2i)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(hex.EncodeToString(output))
}

Documentation

Overview

Package argon2 is a pure Go conversion of the libargon2 library. Exports a simple API with the most essential features.

Index

• Variables
• func Key(password, salt []byte, iterations, parallelism, memory uint32, keyLength int, ...) ([]byte, error)
• type Variant

Variables

var (
	ErrIncorrectType      = errors.New("argon2: Invalid type passed (must be either Argon2i or Argon2d)")
	ErrIncorrectParameter = errors.New("argon2: Incorrect parameter passed to the argon function")
	ErrOutputPtrNull      = errors.New("argon2: Output must be an allocated slice")
	ErrOutputTooShort     = errors.New("argon2: Output is too short")
	ErrOutputTooLong      = errors.New("argon2: Output is too long")
	ErrPwdTooShort        = errors.New("argon2: Password is too short")
	ErrPwdTooLong         = errors.New("argon2: Password is too long")
	ErrSaltTooShort       = errors.New("argon2: Salt is too short")
	ErrSaltTooLong        = errors.New("argon2: Salt is too long")
	ErrSecretTooShort     = errors.New("argon2: Secret is too short")
	ErrSecretTooLong      = errors.New("argon2: Secret is too long")
	ErrADTooShort         = errors.New("argon2: Additional data is too short")
	ErrADTooLong          = errors.New("argon2: Additional data is too long")
	ErrMemoryTooLittle    = errors.New("argon2: Too little memory passed")
	ErrMemoryTooMuch      = errors.New("argon2: Too much memory passed")
	ErrTimeTooSmall       = errors.New("argon2: Time cost too small")
	ErrTimeTooLarge       = errors.New("argon2: Time cost too high")
	ErrLanesTooFew        = errors.New("argon2: Too few lanes")
	ErrLanesTooMany       = errors.New("argon2: Too many lanes")
	ErrThreadsTooFew      = errors.New("argon2: Too few threads")
	ErrThreadsTooMany     = errors.New("argon2: Too many threads")
	ErrThreadFail         = errors.New("argon2: Thread failed")
)

Various errors returned by the library

Functions

func Key

func Key(password, salt []byte, iterations, parallelism, memory uint32, keyLength int, variant Variant) ([]byte, error)

Key derives an Argon2(i|d) hash from the input.

Types

type Variant

type Variant uint8

Variant is the type of algorithm to use

const (
	Argon2d Variant = iota
	Argon2i
)

Argon2i uses data-derived pseudorandom numbers, protecting from side-channel attacks.