2.0 release (#1)

* allow for custom RNGs and for isolation of instances of Cryptipass

* move certification process to tests

* add custom patterns for password generation

* distill markov chain dynamically, allowing for custom languages (word-lists)

* add examples, simplify and streamline readme

Author: francescoalemanno

README.md

@@ -1,80 +1,113 @@
-# Cryptipass
-NOTE: **We also have a [CLI](cmd/genpw) available for non-library uses.**
-Cryptipass is a Go package designed to generate secure passphrases composed of human-readable words. The passphrases are generated with a focus on both security (through entropy) and usability by combining cryptographic randomness and customizable word generation strategies. 
+# cryptipass
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/francescoalemanno/cryptipass)](https://goreportcard.com/report/github.com/francescoalemanno/cryptipass)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GoDoc](https://godoc.org/github.com/francescoalemanno/cryptipass?status.svg)](https://pkg.go.dev/github.com/francescoalemanno/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
 
-- **Cryptographically secure randomization**: Uses `crypto/rand` for generating random data to seed the passphrase generation process, ensuring the highest level of security.
-- **Customizable passphrase length**: The number of words in the passphrase can be controlled by the user.
-- **Entropy calculation**: Provides an exact evaluation of the total entropy for the generated passphrase, helping users understand the strength of their passphrase.
-- **Configurable word lengths**: Words within the passphrase can vary in length, ensuring better randomness and complexity.
+- **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 use the `cryptipass` package in your project, you need to install it using Go's package management:
+To install `cryptipass`, use `go get`:
 
 ```bash
 go get github.com/francescoalemanno/cryptipass
 ```
 
-Then import it in your Go files:
+Then, import it into your project:
 
 ```go
 import "github.com/francescoalemanno/cryptipass"
 ```
 
-## Usage
+NOTE: **We also have a [CLI](cmd/genpw) available for non-library uses.**
 
-### Generate a Passphrase
+---
 
-The primary function of the `cryptipass` package is to generate secure passphrases. You can generate a new passphrase using the `NewPassphrase` function. You can specify how many words you want in the passphrase, and the function returns the passphrase and its total entropy.
+## Quick Start
 
-Example:
+Here's how to generate a passphrase using the default word style:
 
 ```go
 package main
 
 import (
 	"fmt"
-	"cryptipass"
+	"github.com/francescoalemanno/cryptipass"
 )
 
 func main() {
-	passphrase, entropy := cryptipass.NewPassphrase(5)
-	fmt.Printf("Passphrase: %s\n", passphrase)
-	fmt.Printf("Entropy: %.2f bits\n", entropy)
+	// 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)
 }
 ```
 
-### Example Output:
+Want more control over the pattern? Use `GenFromPattern`:
 
+```go
+// Generate a password with pattern: Word-Number-Symbol
+pass, entropy := gen.GenFromPattern("w-d-s") // eg. opantmene-4-%
+fmt.Println("Generated Password:", pass)
 ```
-Passphrase: jesside.flyperm.aunsis.dertsy
-Entropy: 97.63 bits
-```
 
-### Word Generation
+Possible patterns are formed by combining:
+- 'w' lowercase word, 'W' for uppercase word.
+- 'c' a lowercase character, 'C' a uppercase character.
+- 's' symbol, 'd' digit.
+  
+other symbols are interpolated in the final password and to interpolate one of the reserved symbols use escaping with "\".
+
+---
 
-Internally, the package uses a series of functions to generate words of varying lengths. Each word contributes a certain amount of entropy, calculated during the generation process.
+## Custom Word Lists
 
-- `GenMixWord()`: Generates a random word of mixed length, returning both the word and its entropy.
-- `GenWord(n int)`: Generates a word of exactly `n` characters.
-- `PickLength()`: Picks a random length for a word.
-- `PickNext()`: Generates the next part of a word based on the current string.
+You can customize the word style by creating a new instance from your own token set:
 
-## Notes
+```go
+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.
 
-- The package seeds the random number generator with `crypto/rand`, making it cryptographically secure. In scenarios where cryptographic security is not necessary and faster execution is preferred, the package also provides an alternative (commented out) `PCG` random number generator.
-- The entropy provided in the output is a measure of how unpredictable the passphrase is. The higher the entropy, the more secure the passphrase is.
+pass, entropy := gen.GenPassphrase(3)
+fmt.Println("Custom Passphrase:", pass) //e.g. alphar.bravo.delta
+fmt.Println("Entropy:", entropy)
+```
 
-## Contributing
+---
+
+## Documentation
 
-Contributions are welcome! If you encounter any issues or have feature suggestions, feel free to open an issue or a pull request on the GitHub repository.
+Full API documentation is available at [GoDoc](https://pkg.go.dev/github.com/francescoalemanno/cryptipass).
+
+---
 
 ## License
 
-This project is licensed under the MIT License.
+`cryptipass` is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome! Feel free to check out [issues](https://github.com/francescoalemanno/cryptipass/issues) or open a pull request.
 
 ---
 
-Happy coding and stay secure with Cryptipass!
+**cryptipass** – Secure, flexible, and pronounceable passphrases for your Go applications.

cmd/genpw/README.md

@@ -1,95 +1,104 @@
-# genpw - CryptiPass CLI
+# genpw
 
-`genpw` is a simple command-line interface (CLI) for generating high-entropy, pronounceable passphrases using the CryptiPass library. It allows users to specify the number of words in each passphrase and the number of passphrases to generate, making it easy to quickly create secure, human-friendly passwords directly from the terminal.
-
-This tool is part of the [CryptiPass](https://github.com/francescoalemanno/cryptipass) project and resides in the `cmd/genpw` subdirectory.
+**genpw** is a command-line tool that generates secure, pronounceable passwords and passphrases using customizable patterns. Built on top of the `cryptipass` library, **genpw** provides flexible options for creating memorable, yet strong passphrases with high entropy, making it ideal for secure applications, authentication, and more.
 
 ## Features
 
-- **Generate Secure Passphrases**: Easily generate high-entropy, pronounceable passphrases with customizable length.
-- **Customizable Output**: Control the number of words per passphrase and how many passphrases you want to generate.
-- **Lightweight and Easy to Use**: Simple CLI flags for ease of use and quick password generation.
+- Generate secure, pronounceable passwords.
+- Customizable patterns for letters, numbers, symbols, and word formats.
+- Visual strength meter for each generated passphrase.
+- Cryptographic random number generator for secure randomness.
+- High entropy and randomness assurance.
+
+---
 
 ## Installation
 
-To install the `genpw` CLI, first ensure you have Go installed. Then run:
+To install **genpw**, use `go install`:
 
 ```bash
 go install github.com/francescoalemanno/cryptipass/cmd/genpw@latest
 ```
 
-This will install the `genpw` binary in your `$GOPATH/bin` directory.
+Ensure `$GOPATH/bin` is added to your `PATH` to run the command directly.
+
+---
 
 ## Usage
 
-Once installed, you can generate passphrases by running `genpw` with the following options:
+You can generate a set of passwords with the desired pattern using the following command:
 
+```bash
+genpw -p [PATTERN] -n [NUMBER OF PASSWORDS]
 ```
-Usage: genpw [flags]
 
-Flags:
-  -p uint
-        number of passwords to generate (default 4)
-  -w uint
-        number of words per password (default 4)
+### Pattern Options
 
-  -c    run entropy certification algorithm (for developers)
-```
+- **w**: lowercase word.
+- **W**: uppercase word.
+- **c**: lowercase character.
+- **C**: uppercase character.
+- **d**: digit.
+- **s**: symbol.
 
-### Example Commands
+### Example
 
-1. **Generate 4 passphrases with 4 words each** (default):
+Generate 6 passphrases using a pattern of three words (with one capitalized), a two-digit number, and two lowercase characters:
 
 ```bash
-genpw
+genpw -p "W.w.w.ddcc" -n 6
 ```
 
-This will output something like:
-
-```
-       ENTROPY |          PASSPHRASE
-+++++++++++++++|++++++++++++++++++++++++++++++++
-        65.57  |  ammud.ruffl.ummi.shing
-        82.76  |  epavoi.hakeyer.bles.monfin
-        82.91  |  everap.gighte.clap.baselec
-        85.93  |  stash.laxor.surevida.dexqy
+Sample output:
+
+```bash    
+Passphrase                          Log10(Guesses)    Log2Entropy      Strength
+                                                                      
+Mortw.retainish.quater.66es            21.49             72.40       [===========.]
+Defamito.repeac.stateryb.91he          23.75             79.90       [============]
+Grazi.subsider.pravi.83de              20.14             67.92       [==========..]
+Alishin.dumpedial.prayingin.45po       23.85             80.23       [============]
+Atoryone.imputt.moodly.76op            19.66             66.32       [==========..]
+Hurred.buffyeare.uphonetin.97co        23.22             78.12       [============]
 ```
 
-2. **Generate 2 passphrases with 6 words each**:
+### Parameters
 
-```bash
-genpw -w 6 -p 2
-```
+- **`-p`**: Define the pattern for password generation (default: `W.w.w`).
+- **`-n`**: Specify the number of passwords to generate (default: `6`).
 
-The output might look like:
+---
 
-```
-       ENTROPY |          PASSPHRASE
-+++++++++++++++|++++++++++++++++++++++++++++++++
-       119.97  |  tubse.stnew.critedi.priu.bugger.crokess
-       136.65  |  stedin.overjan.gifteto.overepr.comiz.unrupee
-```
+## Password Strength
 
-### Entropy Considerations
+Each generated passphrase includes a strength meter, represented by a bar between `0` and `12` characters, where `=` indicates strength and `.` indicates relative weakness.
 
-Each word generated by CryptiPass has on average more than 21 bits of entropy. For example:
-- A 4-word passphrase has roughly 84 bits of entropy.
-- A 6-word passphrase has approximately 126 bits of entropy.
+- **Log10(Guesses)**: The estimated number of guesses (in log10 scale) required to crack the password.
+- **Log2Entropy**: The entropy (in bits) of the passphrase, reflecting its unpredictability.
 
-This makes the passphrases highly secure, even against brute-force attacks.
+---
 
-## Certification (Debug/Development Mode)
+## Customization
 
-For debugging or testing purposes, the `certify` function can be used to track the entropy of generated words over large runs, it has to be used if another vocabulary is distilled into random rules for the software.
+You can define your own patterns to create passphrases tailored to your security and usability needs. Patterns can be mixed and matched to create combinations of words, digits, symbols, and characters, offering high flexibility.
 
-## Contributing
+Examples:
 
-Contributions are welcome! Please open an issue or submit a pull request via the [main repository](https://github.com/francescoalemanno/cryptipass).
+- **Pattern**: `"wW.d.s"`
+    - Output: lowercase word, uppercase word, digit, and symbol.
+
+```bash
+genpw -p "wW.d.s" -n 4
+```
+
+---
 
 ## License
 
-This tool is open-source and licensed under the MIT License.
+**genpw** is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.
 
-## Contact
+---
+
+## Contributing
 
-For any questions, issues, or suggestions, please visit the [issue tracker](https://github.com/francescoalemanno/cryptipass/issues) on GitHub.
+Contributions are welcome! Feel free to open an issue or submit a pull request for bug fixes, new features, or improvements.