keyphrase

keyphrase generates cryptographically random passwords, EFF-list passphrases, and BIP-39 mnemonics for Go. Selection is unbiased, policies are validated before generation, entropy is derived from the exact output distribution, and randomness is injectable through a context-aware interface.

This module does not hash passwords, implement wallets, derive BIP-32/BIP-44 keys, store secrets, or distribute credentials. Use password for password hashing and a purpose-built secret manager for storage and distribution.

Install

go get github.com/faustbrian/go-keyphrase/v2

The module requires Go 1.27.0 or later.

Status and portability

The v2 module follows the published compatibility and deprecation policies. Its public packages are portable Go: they have no platform-specific source files and require no operating-system service or external runtime backend. That portability statement does not imply validation on every GOOS and GOARCH combination.

Lifecycle, ownership, and concurrency

Selectors and generators are stateless after construction. The default variants use crypto/rand and may be shared across goroutines. A selector created with a custom randomness source may be shared only when that source supports concurrent ReadContext calls. Callers must not mutate policy slices, custom sources, or destination buffers while an operation is using them.

Contexts, injected randomness sources, policy inputs, and destination buffers remain caller-owned. Validated word lists copy their input and expose immutable lookups; methods that return words, entropy, or generated secrets return caller-owned copies. Generation into a caller buffer occurs only after the complete secret has been produced successfully.

The module starts no goroutines, performs no background work, and owns no files, sockets, services, or other runtime resources. Selectors, generators, lists, and generated values have no Close or Shutdown lifecycle. Callers control cancellation and the lifetime and best-effort clearing of returned secret bytes. See performance and operational limits for cost and cancellation caveats.

Password quick start

policy := password.Policy{
    Length:   20,
    Alphabet: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
    Required: []password.Class{
        {Name: "lower", Characters: "abcdefghijklmnopqrstuvwxyz"},
        {Name: "upper", Characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZ"},
        {Name: "digit", Characters: "0123456789"},
    },
    MinimumEntropyBits: 100,
}
secret, err := password.DefaultGenerator().Generate(ctx, policy)
if err != nil { /* handle without logging the secret */ }
defer clear(secret)

Required classes are sampled from the complete valid output space. The generator does not force classes into fixed positions and does not repair an initial password with a biased shuffle.

Passphrase quick start

list, err := eff.Large()
if err != nil { /* embedded-list integrity failure */ }
phrase, err := passphrase.DefaultGenerator().Generate(ctx, passphrase.Policy{
    WordList:  list,
    Words:     6,
    Separator: " ",
})
defer clear(phrase)

The package embeds both EFF short lists and the 7,776-word long list with pinned source and transformed-content checksums.

BIP-39 quick start

mnemonic, err := bip39.Generate(
    ctx, 256, bip39.English, keyphrase.DefaultSelector(),
)
seed, err := bip39.Seed(ctx, mnemonic, passphrase)
defer clear(seed)

All ten official word lists, every official entropy size, NFKD normalization, checksum validation, ambiguity-aware language detection, and the specified PBKDF2-HMAC-SHA512 derivation are supported. BIP-39 seed derivation is included for interoperability; wallet behavior is intentionally absent.

Moving from v1 to v2 changes every Go import to github.com/faustbrian/go-keyphrase/v2[/package]. bip39.Seed now uses the maintained Go PBKDF2 primitive. It checks cancellation before and after the fixed derivation rather than during its rounds; an in-progress call cannot be preempted by its context. See the BIP-39 guide for the strict FIPS-mode limitation.

The checked-in Example_passphrase is the executable five-minute example. It is compiled and run by the Go example test gate.

Security status

The repository runs official vectors, independent interoperability fixtures, property tests, statistical smoke tests, fuzz targets, race tests, mutation tests, and embedded-list integrity checks. An independent agent cryptographic design review approved the v2 source at 4185b83263be3b13aa26ff0ec84c8dfd5d16c174; this is not a human third-party certification. The review record describes its scope and residual risks. Release still requires the applicable CI and release gates.

Generated byte slices can be cleared as a best-effort measure. Go strings, compiler copies, runtime copies, crash dumps, swap, and downstream copies make complete erasure impossible. See secret lifetime.

Documentation

Use the documentation index for the complete guide set. Start with adoption, the API map, and the executable example. Operational and project navigation is available through troubleshooting, the FAQ, support, security reporting, the changelog, and the license.

For ecosystem-wide construction, ownership, lifecycle, and composition guidance, see the versioned Golib ecosystem index and its Domain utilities family.

License

Project code and BIP-39 material are MIT licensed. EFF-derived list data is used under CC BY 3.0 US. See THIRD_PARTY_NOTICES.md.