kdf

README

Golang Key Derivation Function (KDF) Library

Using argon2id KDF

// create a new instance of Argon2ID using default parameters
k, err := kdf.New(kdf.DefaultConfigArgon2ID())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}

// the `k.SetSalt()` function lets the user set the desired salt to be used by `k,Generate`, instead of generating random bytes

// generate key from given input
k.Generate([]byte("hello, world!"))
fmt.Println(k) // outputs hash and all the parameters in encoded format

h:= k.Key() // returns the derived key 
fmt.Println(h)

// parses an encoded string for verification
k1, err := kdf.Parse(k.String())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println(k1)
fmt.Println(k1.Verify([]byte("hello, world!"))) // verifies the given input matches what was stored

/*
    for some  use cases, we don't need to store the string,
    just the calculated hash from Key(), which makes it harder for
    people to guess what is being done.

    For these kinds of scenarios, create the config using custom parameters
    and run the Verify() function manually.

    BitWarden does something similar to this.
*/

Customizing argon2id parameters

kdf.ConfigArgon2ID {
    Memory:      128 * 1024,
    Iterations:  10,
    Parallelism: 5,
    SaltLength:  16,
    KeyLength:   32,
}

k, err := kdf.New(&kdf.ConfigArgon2ID{
    Memory:      128 * 1024,
    Iterations:  10,
    Parallelism: 5,
    SaltLength:  16,
    KeyLength:   32,
})

// the rest of the usage is the same as above

Using pkbdf2 KDF

// create a new instance of pkbdf2 using default parameters
k, err := kdf.New(kdf.DefaultConfigPBKDF2())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}

// the `k.SetSalt()` function lets the user set the desired salt to be used by `k,Generate`, instead of generating random bytes

// generate key from given input
k.Generate([]byte("hello, world!"))
fmt.Println(k) // outputs hash and all the parameters in encoded format

h:= k.Key() // returns the derived key 
fmt.Println(h)

// parses an encoded string for verification
k1, err := kdf.Parse(k.String())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println(k1)
fmt.Println(k1.Verify([]byte("hello, world!"))) // verifies the given input matches what was stored

Customizing pkbdf2 parameters

kdf.ConfigPBKDF2 {
    Iterations:  1000000,
    SaltLength:  16,
    KeyLength:   32,
}

k, err := kdf.New(&kdf.ConfigPBKDF2{
    Iterations: 1000000,
    SaltLength: 16,
    KeyLength:  32,
})

// the rest of the usage is the same as above

Documentation

Index

• type ConfigArgon2ID
  • func DefaultConfigArgon2ID() (kdfA *ConfigArgon2ID)
  • func (aCfg *ConfigArgon2ID) Instance() (cfg any)
• type ConfigPBKDF2
  • func DefaultConfigPBKDF2() (kdfP *ConfigPBKDF2)
  • func (pCfg *ConfigPBKDF2) Instance() (cfg any)
• type KDF
  • func New[T *ConfigArgon2ID | *ConfigPBKDF2](cfg T) (k KDF, err error)
  • func Parse(inputStr string) (kdf KDF, err error)
• type KDFArgon2ID
  • func NewKDFArgon2ID(cfg *ConfigArgon2ID) (a *KDFArgon2ID)
  • func ParseArgon2ID(inputStr string) (a *KDFArgon2ID, err error)
  • func (a *KDFArgon2ID) Generate(input []byte)
  • func (a *KDFArgon2ID) Key() (key []byte)
  • func (a *KDFArgon2ID) SetSalt(salt []byte)
  • func (a *KDFArgon2ID) String() (str string)
  • func (a *KDFArgon2ID) Verify(input []byte) (ok bool)
• type KDFPBKDF2
  • func NewKDFPBKDF2(cfg *ConfigPBKDF2) (p *KDFPBKDF2)
  • func ParsePBKDF2(inputStr string) (p *KDFPBKDF2, err error)
  • func (p *KDFPBKDF2) Generate(input []byte)
  • func (p *KDFPBKDF2) Key() (key []byte)
  • func (p *KDFPBKDF2) SetSalt(salt []byte)
  • func (p *KDFPBKDF2) String() (str string)
  • func (p *KDFPBKDF2) Verify(input []byte) (ok bool)
• type THashFunc
  • func (t THashFunc) String() (str string)
• type Type
  • func (t Type) String() (str string)

Types

type ConfigArgon2ID

type ConfigArgon2ID struct {
	Type        Type
	Memory      uint32
	Iterations  uint32
	Parallelism uint8
	SaltLength  uint32
	KeyLength   uint32
	Salt        []byte
}

ConfigArgon2ID - configuration details for argon2id

func DefaultConfigArgon2ID

func DefaultConfigArgon2ID() (kdfA *ConfigArgon2ID)

DefaultConfigArgon2ID - returns default configuration for Argon2ID

func (*ConfigArgon2ID) Instance

func (aCfg *ConfigArgon2ID) Instance() (cfg any)

type ConfigPBKDF2

type ConfigPBKDF2 struct {
	Type       Type
	Iterations int
	SaltLength uint32
	KeyLength  int
	HashFunc   THashFunc

	Salt []byte
	// contains filtered or unexported fields
}

ConfigPBKDF2 - configuration details for pbkdf2

func DefaultConfigPBKDF2

func DefaultConfigPBKDF2() (kdfP *ConfigPBKDF2)

DefaultConfigPBKDF2 - returns default configuration for PBKDF2

func (*ConfigPBKDF2) Instance

func (pCfg *ConfigPBKDF2) Instance() (cfg any)

type KDF

type KDF interface {
	SetSalt(salt []byte)
	Generate(input []byte)
	Verify(input []byte) (ok bool)
	Key() (key []byte)
	String() (str string)
}

KDF - interface for different implementations of key derivation functions

func New

func New[T *ConfigArgon2ID | *ConfigPBKDF2](cfg T) (k KDF, err error)

func Parse

func Parse(inputStr string) (kdf KDF, err error)

Parse - parses an encoded string and returns an instance of KDF

type KDFArgon2ID

type KDFArgon2ID struct {
	*ConfigArgon2ID
	// contains filtered or unexported fields
}

KDFArgon2ID - structure for argon2id key derivation function

func NewKDFArgon2ID

func NewKDFArgon2ID(cfg *ConfigArgon2ID) (a *KDFArgon2ID)

NewKDFArgon2ID - creates a new instance of Argon2ID using the given configuration parameters

func ParseArgon2ID

func ParseArgon2ID(inputStr string) (a *KDFArgon2ID, err error)

ParseArgon2ID - parses an argon2id output format and generates a KDF with the configuration

func (*KDFArgon2ID) Generate

func (a *KDFArgon2ID) Generate(input []byte)

Generate - generates a input from the input

func (*KDFArgon2ID) Key

func (a *KDFArgon2ID) Key() (key []byte)

Key - returns the computed hash

func (*KDFArgon2ID) SetSalt

func (a *KDFArgon2ID) SetSalt(salt []byte)

SetSalt - sets a custom salt

func (*KDFArgon2ID) String

func (a *KDFArgon2ID) String() (str string)

String - returns an encoded representation of the derived key with the parameters used

func (*KDFArgon2ID) Verify

func (a *KDFArgon2ID) Verify(input []byte) (ok bool)

Verify - verifies a given input with what is stored

type KDFPBKDF2

type KDFPBKDF2 struct {
	*ConfigPBKDF2
	// contains filtered or unexported fields
}

KDFPBKDF2 - structure for pkbdf2 key derivation function

func NewKDFPBKDF2

func NewKDFPBKDF2(cfg *ConfigPBKDF2) (p *KDFPBKDF2)

NewKDFPBKDF2 - creates a new instance of PBKDF2 using the given configuration parameters

func ParsePBKDF2

func ParsePBKDF2(inputStr string) (p *KDFPBKDF2, err error)

ParsePBKDF2 - parses an pbkdf2 output format and generates a KDF with the configuration

func (*KDFPBKDF2) Generate

func (p *KDFPBKDF2) Generate(input []byte)

Generate - generates a input from the input

func (*KDFPBKDF2) Key

func (p *KDFPBKDF2) Key() (key []byte)

Key - returns the computed hash

func (*KDFPBKDF2) SetSalt

func (p *KDFPBKDF2) SetSalt(salt []byte)

SetSalt - sets a custom salt

func (*KDFPBKDF2) String

func (p *KDFPBKDF2) String() (str string)

String - returns an encoded representation of the derived key with the parameters used

func (*KDFPBKDF2) Verify

func (p *KDFPBKDF2) Verify(input []byte) (ok bool)

Verify - verifies a given input with what is stored

type THashFunc

type THashFunc uint8

THashFunc - supported hash functions for pkbdf2

const (
	SHA256 THashFunc = iota + 1
	SHA512
	SHA3256
	SHA3384
	SHA3512
)

func (THashFunc) String

func (t THashFunc) String() (str string)

type Type

type Type uint8

Type - custom type for KDF

const (
	// PBKDF2 - password based key derivation function
	PBKDF2 Type = iota + 1

	// ARGON2ID - uses argon2id
	ARGON2ID
)

func (Type) String

func (t Type) String() (str string)

String - returns name of KDF