README
¶
argon2go
A tiny library that contains an argon2 C binding inspired by go-argon.
Documentation
Please refer to the godoc pages for documentation.
Versioning
This project release version format follows Semantic Versioning.
Contributing
Pull requests and issue reports are welcomed.
License
This project is licensed under Apache License Version 2.0
Documentation
¶
Overview ¶
Package argon2go contains a simple argon2 <https://github.com/P-H-C/phc-winner-argon2/> binding inspired by go-argon <https://github.com/tvdburgt/go-argon2>.
Brief ¶
The package offers a simple interface Hasher with argon2 default C binding implementation, the implementation implicitly generates salt based on a secure random byte array while encoding.
Usage ¶
Be sure that you have argon2 development C library is installed correctly along with its header on your system, then get the this library:
$ go get -u github.com/adzr/argon2go
Then, import the package:
import ( "github.com/adzr/argon2go" )
Example ¶
Create an argon2 hasher with the default options:
// Iterations: 8 // Memory: 65536 KB // Parallelism: 8 // HashLength: 64 // SaltLength: 64 // Mode: Argon2ModeID // Version: Argon2Version13 hasher := argon2go.CreateArgon2()
Options can be specified in the following way:
hasher := argon2go.CreateArgon2(argon2go.Argon2Parallelism(4), argon2go.Argon2HashLength(32))
Once you have a hasher instance, you can call the encode and verify functions:
var (
err error
hashed []byte
verified bool
)
if hashed, err = hasher.Encode([]byte(secretString)); err != nil {
panic(err) // or handle however you want.
}
if verified, err = hasher.Verify([]byte(secretString), hashed); err != nil {
panic(err)
}
println(verified) // This should output true.
Index ¶
- Constants
- Variables
- type Argon2Config
- type Argon2Option
- func Argon2HashLength(hashLength int) Argon2Option
- func Argon2Iterations(iterations int) Argon2Option
- func Argon2Memory(memory int) Argon2Option
- func Argon2Mode(mode int) Argon2Option
- func Argon2Parallelism(parallelism int) Argon2Option
- func Argon2SaltLength(saltLength int) Argon2Option
- func Argon2Version(version int) Argon2Option
- type Hasher
Constants ¶
const ( // Argon2ModeD is a constant value flag represents argon2d mode in argon2 algorithm. Argon2ModeD int = C.Argon2_d // Argon2ModeI is a constant value flag represents argon2i mode in argon2 algorithm. Argon2ModeI int = C.Argon2_i // Argon2ModeID is a constant value flag represents argon2id mode in argon2 algorithm. Argon2ModeID int = C.Argon2_id // Argon2Version10 is a constant value flag represents argon2 implementation version 10. Argon2Version10 int = C.ARGON2_VERSION_10 // Argon2Version13 is a constant value flag represents argon2 implementation version 13. Argon2Version13 int = C.ARGON2_VERSION_13 // Argon2VersionDefault is a constant value flag represents argon2 implementation default version. Argon2VersionDefault int = C.ARGON2_VERSION_NUMBER )
Variables ¶
var ( // ErrEmptyInput returned if the raw input parameter is nil or empty on calling Encode or Verify. ErrEmptyInput = errors.New("empty input specified") // ErrEmptyHash returned if the hash parameter is nil or empty on calling Verify. ErrEmptyHash = errors.New("empty hash specified") // ErrNotConfigured returned on calling Encode or Verify // if the Argon2 Hasher instance is not configured. ErrNotConfigured = errors.New("instance is not configured properly") // ErrInvalidArgon2Mode returned on calling Verify if the Argon2 mode // extracted from the specified hash is invalid. ErrInvalidArgon2Mode = errors.New("invalid argon2 mode") )
Functions ¶
This section is empty.
Types ¶
type Argon2Config ¶
type Argon2Config struct {
// Iterations is the number of iterations, more
// iterations, more secure hash but slower hashing.
Iterations int
// Memory is the memory cost in kilobytes
// requested to process the hash function.
Memory int
// Parallelism is the number of concurrent passes
// used in the hash function.
Parallelism int
// HashLength is the length in bytes of the hash output.
HashLength int
// SaltLength is the length in bytes of the salt.
SaltLength int
// Mode is the variation of algorithm meant to be used.
// Possible values:
// Argon2ModeD
// Argon2ModeI
// Argon2ModeID
Mode int
// Version is the used algorithm version.
// Possible values:
// Argon2Version10
// Argon2Version13
// Argon2VersionDefault
Version int
}
Argon2Config is a configuration struct meant to carry Argon2 configuration through the initialization process.
type Argon2Option ¶
type Argon2Option func(conf *Argon2Config)
Argon2Option is a callback function that is meant to configure a provided reference to Argon2Config structure.
func Argon2HashLength ¶
func Argon2HashLength(hashLength int) Argon2Option
Argon2HashLength returns an Argon2Option that configures a provided reference of Argon2Config with the specified hash length in bytes.
func Argon2Iterations ¶
func Argon2Iterations(iterations int) Argon2Option
Argon2Iterations returns an Argon2Option that configures a provided reference of Argon2Config with the specified iterations.
func Argon2Memory ¶
func Argon2Memory(memory int) Argon2Option
Argon2Memory returns an Argon2Option that configures a provided reference of Argon2Config with the specified memory size in kilobytes.
func Argon2Mode ¶
func Argon2Mode(mode int) Argon2Option
Argon2Mode returns an Argon2Option that configures a provided reference of Argon2Config with the specified mode.
func Argon2Parallelism ¶
func Argon2Parallelism(parallelism int) Argon2Option
Argon2Parallelism returns an Argon2Option that configures a provided reference of Argon2Config with the specified number of passes (parallelism).
func Argon2SaltLength ¶
func Argon2SaltLength(saltLength int) Argon2Option
Argon2SaltLength returns an Argon2Option that configures a provided reference of Argon2Config with the specified salt length in bytes.
func Argon2Version ¶
func Argon2Version(version int) Argon2Option
Argon2Version returns an Argon2Option that configures a provided reference of Argon2Config with the specified version.
type Hasher ¶
type Hasher interface {
// Encode receives a byte array and returns its hash
// representation as a byte array depending on the
// algorithm implemented, it also may return an error
// with a nil byte array on failure.
Encode([]byte) ([]byte, error)
// Verify receives two byte arrays and simply checks
// if the second represents the hash value of the
// first, if they match it returns true, else false.
// It also returns an error on failure to check.
Verify([]byte, []byte) (bool, error)
}
Hasher is a common interface that represents a hashing algorithm implementation.
func CreateArgon2 ¶
func CreateArgon2(options ...Argon2Option) Hasher
CreateArgon2 returns a reference to a Hasher implementation that uses Argon2 algorithm to hash and verify a secret. For more information on Argon2 refer to: https://github.com/P-H-C/phc-winner-argon2
Source Files