password

Documentation

Overview

Package password provides a library for generating high-entropy random password strings via the crypto/rand package.

res, err := Generate(64, 10, 10, false, false)
if err != nil  {
  log.Fatal(err)
}
log.Printf(res)

Most functions are safe for concurrent use.

Index

• Constants
• Variables
• func Generate(input Input) (string, error)
• func MustGenerate(input Input) string
• type Generator
  • func NewGenerator() Generator
  • func (g Generator) Generate(input Input) (string, error)
  • func (g Generator) MustGenerate(input Input) string
  • func (g Generator) WithDigits(digits string) Generator
  • func (g Generator) WithLowerLetters(lowerLetters string) Generator
  • func (g Generator) WithSymbols(symbols string) Generator
  • func (g Generator) WithUpperLetters(upperLetters string) Generator
• type Input

Examples

• Generate
• Generator.Generate
• MustGenerate
• NewGenerator (Custom)
• NewGenerator (Nil)

Constants

const (
	// LowerLetters is the list of lowercase letters.
	LowerLetters = "abcdefghijklmnopqrstuvwxyz"

	// UpperLetters is the list of uppercase letters.
	UpperLetters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

	// Digits is the list of permitted digits.
	Digits = "0123456789"

	// Symbols is the list of symbols.
	Symbols = "~!@#$%^&*()_+`-={}|[]\\:\"<>?,./"
)

Variables

var (
	// ErrExceedsTotalLength is the error returned with the number of digits and
	// symbols is greater than the total length.
	ErrExceedsTotalLength = errors.New("number of digits and symbols must be less than total length")

	// ErrLettersExceedsAvailable is the error returned with the number of letters
	// exceeds the number of available letters and repeats are not allowed.
	ErrLettersExceedsAvailable = errors.New("number of letters exceeds available letters and repeats are not allowed")

	// ErrDigitsExceedsAvailable is the error returned with the number of digits
	// exceeds the number of available digits and repeats are not allowed.
	ErrDigitsExceedsAvailable = errors.New("number of digits exceeds available digits and repeats are not allowed")

	// ErrSymbolsExceedsAvailable is the error returned with the number of symbols
	// exceeds the number of available symbols and repeats are not allowed.
	ErrSymbolsExceedsAvailable = errors.New("number of symbols exceeds available symbols and repeats are not allowed")
)

Functions

func Generate

func Generate(input Input) (string, error)

Generate is the package shortcut for Generator.Generate.

Example

package main

import (
	"log"

	"github.com/juev/go-password/password"
)

func main() {
	res, err := password.Generate(password.Input{
		Length:  64,
		Digits:  10,
		Symbols: 10,
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Print(res)
}

func MustGenerate

func MustGenerate(input Input) string

MustGenerate is the package shortcut for Generator.MustGenerate.

Example

package main

import (
	"log"

	"github.com/juev/go-password/password"
)

func main() {
	// Will panic on error
	res := password.MustGenerate(password.Input{
		Length:  64,
		Digits:  10,
		Symbols: 10,
	})
	log.Print(res)
}

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator is the stateful generator which can be used to customize the list of letters, digits, and/or symbols.

func NewGenerator

func NewGenerator() Generator

NewGenerator creates a new Generator from the specified configuration. If no input is given, all the default values are used. This function is safe for concurrent use.

Example (Custom)

package main

import (
	"github.com/juev/go-password/password"
)

func main() {
	// Customize the list of symbols.
	gen := password.NewGenerator().WithSymbols("!@#$%^()")
	_ = gen // gen.Generate(...)
}

Example (Nil)

package main

import (
	"github.com/juev/go-password/password"
)

func main() {
	// This is exactly the same as calling "Generate" directly. It will use all
	// the default values.
	gen := password.NewGenerator()
	_ = gen // gen.Generate(...)
}

func (Generator) Generate

func (g Generator) Generate(input Input) (string, error)

Generate generates a password with the given requirements. length is the total number of characters in the password. numDigits is the number of digits to include in the result. numSymbols is the number of symbols to include in the result. noUpper excludes uppercase letters from the results. allowRepeat allows characters to repeat.

The algorithm is fast, but it's not designed to be performant; it favors entropy over speed. This function is safe for concurrent use.

Example

package main

import (
	"log"

	"github.com/juev/go-password/password"
)

func main() {
	gen := password.NewGenerator()
	res, err := gen.Generate(password.Input{
		Length:  64,
		Digits:  10,
		Symbols: 10,
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Print(res)
}

func (Generator) MustGenerate

func (g Generator) MustGenerate(input Input) string

MustGenerate is the same as Generate, but panics on error.

func (Generator) WithDigits

func (g Generator) WithDigits(digits string) Generator

WithDigits creates a new Generator from another Generator with specific Digits.

func (Generator) WithLowerLetters

func (g Generator) WithLowerLetters(lowerLetters string) Generator

WithLowerLetters creates a new Generator from another Generator with specific LowerLetters.

func (Generator) WithSymbols

func (g Generator) WithSymbols(symbols string) Generator

WithSymbols creates a new Generator from another Generator with specific Symbols.

func (Generator) WithUpperLetters

func (g Generator) WithUpperLetters(upperLetters string) Generator

WithUpperLetters creates a new Generator from another Generator with specific UpperLetters.

type Input

type Input struct {
	Length      int
	Digits      int
	Symbols     int
	NoUpper     bool
	AllowRepeat bool
	// contains filtered or unexported fields
}

Input used to define input parameters for the generator.