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.0release.
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 ¶
Examples ¶
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.
Variables ¶
This section is empty.
Functions ¶
This section 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.
//
// It's the caller's responsibility to limit the maximum length to prevent
// memory exhaustion via large length values.
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. Instances are not safe for concurrent use.
func (*Diceware) Generate ¶
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.
//
// It's the caller's responsibility to limit the maximum length to prevent
// memory exhaustion via large length values.
Length int
// contains filtered or unexported fields
}
PIN is a policy for generating ChaCha8-based cryptographically strong random PINs. Instances are not safe for concurrent use.
func (*PIN) Generate ¶
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.
//
// It's the caller's responsibility to limit the maximum length to prevent
// memory exhaustion via large length values.
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. Instances are not safe for concurrent use.
func (*Random) Generate ¶
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)
}
Source Files