acopw

README

acopw

Package acopw provides a simple, efficient, and secure way to generate random passwords, passphrases, and PINs using Go. It leverages the speed of math/rand/v2 with the cryptographic security of ChaCha8 for generating random data, ensuring the highest level of randomness, security, and performance.

When generating diceware passwords, it uses a curated list with over 23 thousand words, one of the largest word lists out there.

Sample output:

(#lR?xdVe^o#;|{K>k%Y$,SXnn?nLl[=+|^cf|AWCtA}YoP(Vb=G^rwj]f;u@~Py
u{AQTrcOcHG#/.K>j{?P=\=jm%O>)hC;.Y%l,~fE'v];^@AY!?I}=DzyKlE@GEKb
hefty_spacetime_ENVELOPE_hearing_trend_fossils_unusable
deplored-desert-victory-runtime-coupland-costly-CLASSICS
728079
996388

Installation

To install acopw and use it in your project, run:

go get git.sr.ht/~jamesponddotco/acopw-go@latest

Usage

Random passwords

To generate a random password, use Random and call the Generate() method.

package main

import (
	"fmt"
	"log"
	"os"

	"git.sr.ht/~jamesponddotco/acopw-go"
)

func main() {
	random := &acopw.Random{
		Length:     16,
		UseLower:   true,
		UseUpper:   true,
		UseNumbers: true,
		UseSymbols: true,
	}

	if _, err := fmt.Fprintln(os.Stdout, random.Generate()); err != nil {
		log.Fatal(err)
	}
}

Diceware passwords

To generate a diceware password, use Diceware and call the Generate() method.

package main

import (
	"fmt"
	"log"
	"os"

	"git.sr.ht/~jamesponddotco/acopw-go"
)

func main() {
	diceware := &acopw.Diceware{
		Separator:  "-",
		Length:     6,
		Capitalize: true,
	}

	if _, err := fmt.Fprintln(os.Stdout, diceware.Generate()); err != nil {
		log.Fatal(err)
	}
}

PINs

To generate a PIN, use PIN and call the Generate() method.

package main

import (
	"fmt"
	"log"
	"os"

	"git.sr.ht/~jamesponddotco/acopw-go"
)

func main() {
	pin := &acopw.PIN{
		Length: 6,
	}

	if _, err := fmt.Fprintln(os.Stdout, pin.Generate()); err != nil {
		log.Fatal(err)
	}
}

Contributing

Anyone can help make acopw better. Send patches on the mailing list and report bugs on the issue tracker.

You must sign-off your work using git commit --signoff. Follow the Linux kernel developer's certificate of origin for more details.

All contributions are made under the MIT License.

Acknowledgements

• Tests were mostly written using a combination of Claude 3 and GPT-4.
• Big thanks to the EFF for providing some word lists, which were complimented by me crawling Wikipedia.
• Big thanks to Christopher Wellons for reviewing and auditing the underlying cryptographic implementation for biases and security issues. He also helped with many of the performance optimizations for the v1.0.0 release.

Resources

The following resources are available:

• Package documentation.
• Support and general discussions.
• Patches and development related questions.
• Instructions on how to prepare patches.
• Feature requests and bug reports.

---

Released under the MIT License.

Documentation

Overview

Package acopw provides a simple way to generate cryptographically secure random and diceware passwords, and PINs.

Index

• Constants
• type Diceware
  • func (d *Diceware) Generate() string
• type PIN
  • func (p *PIN) Generate() string
• type Random
  • func (r *Random) Generate() string

Examples

• Diceware.Generate
• PIN.Generate
• Random.Generate

Constants

const DefaultDicewareLength int = 8

DefaultDicewareLength is the default length of a diceware password.

const DefaultPINLength int = 6

DefaultPINLength is the default length of a PIN.

const DefaultRandomLength int = 128

DefaultRandomLength is the default length of a random password.

const ErrInvalidCharset xerrors.Error = "no characters to build password in the charset"

ErrInvalidCharset is returned when the internal character set is empty.

Types

type Diceware

type Diceware struct {

	// Separator is the string used to separate words in the password.
	Separator string

	// Words is a list of words included in the generated password. If the list
	// is empty, a default word list is used.
	Words []string

	// Length is the number of words to include in the generated password. If
	// less than 1, it defaults to 8.
	Length int

	// Capitalize indicates whether a random word should be capitalized.
	Capitalize bool
	// contains filtered or unexported fields
}

Diceware is a policy for generating ChaCha8-based cryptographically strong diceware passwords.

func (*Diceware) Generate

func (d *Diceware) Generate() string

Generate returns a cryptographically strong diceware password for the policy. It panics if it can't get entropy from the source of randomness.

Example

// Define password policy.
password := acopw.Diceware{
	Length:     7,    // Use 7 words.
	Capitalize: true, // Capitalize the first letter of a random word.
}

// Generate and print a random diceware password. Use os.Stdout in the real
// world.
if _, err := fmt.Fprintln(os.Stderr, password.Generate()); err != nil {
	log.Fatal(err)
}

type PIN

type PIN struct {

	// Length is the length of the generated PIN. If less than 1, it defaults to
	// 6.
	Length int
	// contains filtered or unexported fields
}

PIN is a policy for generating ChaCha8-based cryptographically strong random PINs.

func (*PIN) Generate

func (p *PIN) Generate() string

Generate returns a cryptographically strong PIN for the policy. It panics if it can't get entropy from the source of randomness.

Example

// Define your PIN policy.
pin := acopw.PIN{
	Length: 6, // Generate a 6 digit PIN.
}

// Generate and print a random PIN. Use os.Stdout in the real world.
if _, err := fmt.Fprintln(os.Stderr, pin.Generate()); err != nil {
	log.Fatal(err)
}

type Random

type Random struct {

	// ExcludedCharset is a list of characters that should not be included in
	// the generated password.
	ExcludedCharset []string

	// Length is the length of the password. If less than 1, it defaults to 128.
	Length int

	// UseLower, UseUpper, UseNumbers, and UseSymbols specify whether or not to
	// use the corresponding character class in the generated password.
	//
	// If none of these are true, it defaults to true for all four.
	UseLower   bool
	UseUpper   bool
	UseNumbers bool
	UseSymbols bool
	// contains filtered or unexported fields
}

Random is a policy for generating ChaCha8-based cryptographically strong random passwords.

func (*Random) Generate

func (r *Random) Generate() string

Generate returns a cryptographically strong random password for the policy. It panics if it can't get entropy from the source of randomness or if the internally generated character set is empty.

Example

// Define password policy.
password := acopw.Random{
	ExcludedCharset: []string{
		" ", // Exclude spaces
		"&", // Exclude ampersands
	},
	Length:     64,   // Generate a 64 character password
	UseLower:   true, // Use lowercase letters
	UseUpper:   true, // Use uppercase letters
	UseSymbols: true, // Use symbols
}

// Generate and print a random password. Use os.Stdout in the real world.
if _, err := fmt.Fprintln(os.Stderr, password.Generate()); err != nil {
	log.Fatal(err)
}