README
¶
cryptipass
cryptipass is a flexible, high-entropy passphrase generator that creates secure, pronounceable passwords using a probabilistic model. It's designed for security-conscious developers who need memorable yet strong passphrases.
Features
- Pronounceable Passwords: Generates words based on real-world token patterns, making them easy to remember.
- Highly Customizable: Define your own word list or use pre-defined patterns like symbols, numbers, and mixed-case letters.
- Secure Randomness: Uses cryptographic-grade randomness (
crypto/rand) for generating passphrases. - Entropy Analysis: Built-in entropy calculations and certification to ensure high randomness and strength.
- Pattern-Based Generation: Control password structure using customizable patterns (e.g., words, digits, symbols).
Installation
To install cryptipass, use go get:
go get github.com/francescoalemanno/cryptipass/v3
Then, import it into your project:
import "github.com/francescoalemanno/cryptipass/v3"
NOTE: We also have a CLI available for non-library uses.
Quick Start
Here's how to generate a passphrase using the default word style:
package main
import (
"fmt"
"github.com/francescoalemanno/cryptipass/v3"
)
func main() {
// Create a new cryptipass generator
gen := cryptipass.NewInstance()
// Generate a 4-word passphrase
passphrase, entropy := gen.GenPassphrase(4)
fmt.Println("Passphrase:", passphrase) //e.g. netica.peroundl.opantmene.symnals
fmt.Println("Entropy:", entropy)
}
Want more control over the pattern? Use GenFromPattern:
// Generate a password with pattern: Word-Number-Symbol
pass, entropy := gen.GenFromPattern("w-d-s") // eg. opantmene-4-%
fmt.Println("Generated Password:", pass)
Possible patterns are formed by combining:
- 'w' lowercase word, 'W' for uppercase word.
- 'c' a lowercase token, 'C' a uppercase token.
- 's' symbol, 'd' digit.
other symbols are interpolated in the final password and to interpolate one of the reserved symbols use escaping with "".
Custom Word Lists
You can customize the word style by creating a new instance from your own token set:
myTokens := []string{"alpha", "bravo", "charlie", "delta"}
gen := cryptipass.NewCustomInstance(myTokens, 1) //instead of 1, try 2,3,4 to see the tradeoff between fidelity to the wordlist and entropy gain.
pass, entropy := gen.GenPassphrase(3)
fmt.Println("Custom Passphrase:", pass) //e.g. alphar.bravo.delta
fmt.Println("Entropy:", entropy)
Documentation
Full API documentation is available at GoDoc.
License
cryptipass is licensed under the MIT License. See LICENSE for details.
Contributing
Contributions, issues, and feature requests are welcome! Feel free to check out issues or open a pull request.
cryptipass – Secure, flexible, and pronounceable passphrases for your Go applications.
Documentation
¶
Overview ¶
Package cryptipass provides a flexible and secure password generation system that creates pronounceable passphrases based on a probabilistic model.
It is designed for security-conscious developers who need to generate strong, memorable passwords.
The package supports custom word lists and pattern-based password generation, allowing users to tailor the output to their needs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WordListDebug ¶
func WordListDebug() []string
func WordListEFF ¶
func WordListEFF() []string
WordListEFF() return EFF long word list Credit goes to Joseph Bonneau from EFF url : https://www.eff.org/dice
func WordListItalian ¶
func WordListItalian() []string
func WordListLatin ¶
func WordListLatin() []string
WordListLatin() return DICEWARE latin word list Credit goes to Sebastian Możejko under a CC-BY license. url : https://theworld.com/~reinhold/diceware.html
Types ¶
type Generator ¶
type Generator struct {
Rng *rand.Rand // Rng remains public to allow custom RNGS
// contains filtered or unexported fields
}
Generator is a structure that holds the state of the password generator instance. It includes a random number Generator (Rng) and a jump table (JumpTable) which defines token transition probabilities.
func NewCustomInstance ¶
NewCustomInstance creates a new instance of the cryptipass password generator using a custom word list. The word list should consist of tokens (words) that will be used to construct pronounceable passphrases.
The function returns a pointer to a generator instance, which can be used to generate passphrases with the provided word list.
The generator uses a probabilistic transition model, initialized with a pre-defined set of tokens to construct pronounceable passwords based on patterns of letter transitions.
Example usage:
tokens := []string{"alpha", "bravo", "charlie", "delta"}
gen := cryptipass.NewCustomInstance(tokens, 1)
passphrase, entropy := gen.GenPassphrase(4)
Parameters:
- tokens []string: A list of words (tokens) from which the generator will build passphrases.
- chain_depth int: The correlation length used to distill the probabilistic model.
Returns:
- *generator: A new generator instance using the custom word list.
If the random seed cannot be read from the crypto/rand source, the function will log a fatal error and terminate the application.
func NewInstance ¶
func NewInstance() *Generator
NewInstance creates a new generator using a default word list to produce pronounceable, secure passphrases.
Example usage:
gen := cryptipass.NewInstance() passphrase, entropy := gen.GenPassphrase(4)
This will create a 4-word passphrase with high entropy.
NewInstance is ideal for general use cases where you want to generate secure passphrases with a focus on ease of pronunciation and memorization.
func (*Generator) GenFromPattern ¶
GenFromPattern generates a password or passphrase based on a user-defined pattern.
The pattern string can include special placeholders that dictate the structure of the generated password. Each placeholder corresponds to a specific type of token. The supported placeholders are:
- 'w' : Generates a word in lowercase.
- 'W' : Generates a word with the first letter capitalized.
- 'd' : Generates a random digit (0-9).
- 's' : Generates a random symbol from a predefined set (@#!$%&=?^+-*").
- 'c' : Generates a random lowercase token.
- 'C' : Generates a random capitalized token.
- '\\' : Escapes the next character in the pattern, allowing you to include literal values.
Example usage:
g := cryptipass.NewInstance()
passphrase, entropy := g.GenFromPattern("Ww-d-s")
fmt.Println("Generated passphrase:", passphrase)
fmt.Println("Entropy:", entropy)
This will generate a passphrase consisting of a capitalized word, a lowercase word, a digit, and a symbol, such as "Alpha-bravo-7-$".
The function returns the generated password or passphrase and the estimated entropy in bits, which quantifies its strength.
func (*Generator) GenNextToken ¶
GenNextToken selects the next token based on the current seed (context) and a probabilistic model derived from the transition matrix. It generates a token that is most likely to follow the given string context `seed`.
If the `seed` is too short or does not match any known transitions in the matrix, it falls back to using shorter prefixes until a match is found. The function retries with successively smaller parts of the `seed` until a suitable transition is discovered.
The function returns the selected token as a string and its entropy value.
Parameters:
- seed: A string representing the current context.
Returns:
string: The next token. float64: The entropy value associated with the selected token.
Example:
seed := "th"
nextTok, entropy := generator.GenNextToken(seed)
fmt.Printf("Next token: %s, Entropy: %.2f\n", nextTok, entropy)
Panic:
This function panics if the transition matrix is not initialized or if the selection process encounters an unexpected error while choosing the next token.
func (*Generator) GenPassphrase ¶
GenPassphrase generates a passphrase composed of a specified number of words.
Each word is randomly selected based on transition probabilities, ensuring pronounceability while maintaining strong entropy. The words are separated by dots to improve readability and security (similar to the Diceware method).
This method uses a cryptographically secure random number generator (via `crypto/rand`) for enhanced security.
Parameters:
- words: The number of words to include in the passphrase.
Returns:
- passphrase (string): The generated passphrase, with words separated by dots.
- entropy (float64): The total entropy of the passphrase, measured in bits.
Example:
gen := cryptipass.NewInstance()
passphrase, entropy := gen.GenPassphrase(4)
fmt.Println("Passphrase:", passphrase)
fmt.Println("Entropy:", entropy)
The entropy value reflects the randomness of the passphrase. The higher the entropy, the more secure the passphrase is, making it difficult for attackers to guess.
Source Files
Directories