README
¶
Go HBEDF
Go HBEDF provides functionality for generating deterministic pseudorandom sequences of bytes from human-derived values. A derived seed can be generated from a slice of biographic material, and a secret, across four phases: Key, Extract, Shuffle, an Expand. This is a reference implementation of the Human-Based Entropy Derivation Function (HBEDF), from the specification titled "Deterministic Method of Entropy Derivation from Human Identity and Secrets". The cryptographic keys used across internal derivation phases are Hierarchical Deterministic Symmetric Keys.
Derive a Seed
The hbedf.New function has four input parameters:
ds, err := hbedf.New(h, ibm, secret, opts)
Where:
- h is a hash function (e.g. sha256, sha512).
- ibm is a slice of initial biographic information (e.g. name, date of birth, document number).
- secret is the secret information (e.g. PIN, passphrase) used to generate the key used across internal derivation phases.
- opts are the options for configuring seed derivation.
- path is the derivation path used to generate the internal HD key.
- schema (optional) is the derivation path schema (uses a default schema when an empty string).
- c is an iterations count, for the number of HMAC iterations applied to ibm for strengthening.
- mem is the target memory cost in MiB applied cumulatively across Scrypt invocations during slice shuffling.
- dsLen is the desired byte length of the derived seed.
The h parameter is expected as a hash function with the signature func() hash.Hash. The ibm parameter is expected as a slice of byte slices [][]byte. The secret parameter is expected as a byte slice []byte. The opts parameter is expected as an Opts struct. The New function returns a byte slice.
Opts Type
The Opts type is a struct holding the derivation path, optional derivation path schema, iterations count, target memory cost, and output length.
type Opts struct {
Path string // Derivation path
Schema string // Derivation path schema
C int // Strengthening iterations count
Mem int // Target memory cost
DsLen int // Output length
}
Derivation Phases
The process of deriving a seed is divided into four phases, and each phase can be called from the hbedf package independently. During the first Key phase (hbedf.Key), a hierarchical deterministic (HD) key is generated. A master key is generated from the secret, and a node in a hierarchy descending from the master key is derived using the derivation path, returned as the HD key from the phase. During the second Extract phase (hbedf.Extract), strengthened biographic material sbm and a scrypt N parameter are extracted from initial biographic material ibm, an HMAC iterations count c, and a target memory cost mem. During the third Shuffle phase (hbedf.Shuffle), pseudorandom biographic material pbm is obtained from sbm through a Fisher-Yates shuffle, internally using scrypt-derived keys with options N, r=8, and p=1 in obtaining pseudorandom numbers. During the final Expand phase (hbedf.Expand), output seed material osm is generated from pbm through an iterative HMAC expansion to produce an output of a desired byte length.
Example Use
package main
import (
"crypto/sha256"
"encoding/hex"
"fmt"
"github.com/jacobhaap/go-hbedf"
)
func main() {
// Use sha256
h := sha256.New
// Encode the biographic material
bio := []string{"MUSTERMANN", "ERIKA", "L01X00T47", "12081983"}
ibm := make([][]byte, len(bio))
for i, b := range bio {
ibm[i] = []byte(b)
}
// Encode a secret from a hex string
secret, err := hex.DecodeString("54686520696D6D6F7274616C20736E61696C20697320626568696E6420796F75")
if err != nil {
panic(err)
}
// Set options
opts := hbedf.Opts{
Path: "m/42/0/1/0",
C: 10000,
Mem: 128,
DsLen: 64,
}
// Generate a derived seed
ds, err := hbedf.New(h, ibm, secret, opts)
if err != nil {
panic(err)
}
// Display derived seed
fmt.Println("Derived Seed:", ds)
}
Documentation
¶
Overview ¶
Package hbedf provides functionality for generating derived seeds from initial biographic information and a secret.
Index ¶
- func Expand(h func() hash.Hash, pbm []byte, key *hdsk.HDKey, length int) ([]byte, error)
- func Extract(h func() hash.Hash, ibm [][]byte, key *hdsk.HDKey, c, mem int) ([][]byte, int, error)
- func Key(h func() hash.Hash, secret []byte, schema, path string) (*hdsk.HDKey, error)
- func New(h func() hash.Hash, ibm [][]byte, secret []byte, opts Opts) ([]byte, error)
- func Shuffle(h func() hash.Hash, sbm [][]byte, key *hdsk.HDKey, N int) ([]byte, error)
- type Opts
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Expand ¶
Expand generates output seed material (osm) from pseudorandom biographic material (pbm) by repeatedly applying HMAC to expand the pbm, from a given hash, pbm slice, pointer to an HD key, and output length.
func Extract ¶
Extract extracts strengthened biographic material (sbm) from initial biographic material (ibm), and calculates a scrypt N parameter, from a given hash, ibm slice, pointer to an HD key, iterations count, and target memory cost. The sbm and N produced are suitable for use in the Shuffle phase.
func Key ¶
Key derives a node in a hierarchy and returns a pointer to an HD key, from a given hash, secret, schema, and derivation path. The HD key derived is suitable for use in the Extract, Shuffle, and Expand phases.
func New ¶
New generates a derived seed from initial biographic material (ibm) and a secret, from a given hash, ibm slice, secret, and options.
For example, you can obtain a derived seed by doing:
ds, err := hbedf.New(h, ibm, secret, opts)
From the options, Path and Schema are a derivation path and schema. A default schema is used when an empty string ("") is provided. C is the HMAC iterations count for strengthening. Mem is the target memory cost for scrypt. DsLen is the output byte length of the derived seed.
func Shuffle ¶
Shuffle takes strengthened biographic material (sbm) and shuffles it across two iterations of a Fisher-Yates shuffle to produce pseudorandom biographic material (pbm), from a given hash, sbm slice, pointer to an HD key, and scrypt N parameter. The pbm produced is suitable for use in the Expand phase.
Source Files
Directories