add examples, simplify and streamline readme

francescoalemanno · Oct 6, 2024 · ac3b5ec · ac3b5ec
1 parent 14d7a11
commit ac3b5ec
Show file tree

Hide file tree

Showing 7 changed files with 158 additions and 97 deletions.
diff --git a/README.md b/README.md
@@ -56,7 +56,16 @@ Entropy: 133.21 bits
 
 ### Generate a Password according to a pattern
 
-You can generate a new password using the `GenFromPattern` function. You can specify how many words you want in the passphrase, and the function returns the passphrase and its total entropy.
+You can generate a new password using the `GenFromPattern` function. You can specify how many words, symbols, digits you want in the passphrase by defining a pattern.
+
+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 "\".
+
+The function returns the passphrase and its total entropy.
 
 Example:
 
@@ -67,14 +76,7 @@ import (
 	"fmt"
 	"github.com/francescoalemanno/cryptipass"
 )
-/*
-	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.
-	To interpolate one of the reserved symbols use escaping with "\".
-*/
+
 func main() {
 	cp := cryptipass.NewInstance()
 	passphrase, entropy := cp.GenFromPattern("W-w.cccc.CCCC(ss)[20dd]")

diff --git a/cmd/genpw/README.md b/cmd/genpw/README.md
@@ -1,117 +1,111 @@
-# genpw - CryptiPass CLI
+# cryptipass
 
-`genpw` is a simple command-line interface (CLI) for generating high-entropy, pronounceable passphrases using the CryptiPass library. It allows users to specify the pattern used to generate each passphrase (e.g. the number of words, symbols, digits), the number of passphrases to generate making it easy to quickly create secure, human-friendly passwords directly from the terminal.
+[![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)
 
-This tool is part of the [CryptiPass](https://github.com/francescoalemanno/cryptipass) project and resides in the `cmd/genpw` subdirectory.
+**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
 
-- **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.
+- **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 the `genpw` CLI, first ensure you have Go installed. Then run:
+To install `cryptipass`, use `go get`:
 
 ```bash
-go install github.com/francescoalemanno/cryptipass/cmd/genpw@latest
+go get github.com/francescoalemanno/cryptipass
 ```
 
-This will install the `genpw` binary in your `$GOPATH/bin` directory.
+Then, import it into your project:
 
-## Usage
+```go
+import "github.com/francescoalemanno/cryptipass"
+```
 
-Once installed, you can generate passphrases by running `genpw` with the following options:
+---
 
-```bash
-Usage of genpw:
-  -n uint
-        number of passwords to generate (default 6)
-  -p string
-        pattern used to generate passphrase e.g. try:
-                -p WWW20dd
-
-                other 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.
-                 (default "W.w.w")
-```
+## Quick Start
 
-### Example Commands
+Here's how to generate a passphrase using the default word style:
 
-1. **Generate 6 passphrases with 3 words each** (default):
+```go
+package main
 
-```bash
-genpw
-```
+import (
+	"fmt"
+	"github.com/francescoalemanno/cryptipass"
+)
 
-This will output something like:
+func main() {
+	// Create a new cryptipass generator
+	gen := cryptipass.NewInstance()
 
-```bash
-Passphrase                    Log10(Guesses)    Log2Entropy      Strength
-
-Candox.swortone.harvingl         23.37             78.64       [============]
-Kinywaya.preterpr.reefrate       24.31             81.76       [============]
-Ratererl.ruse.elikewa            20.44             68.92       [==========..]
-Relemalo.anli.systuri            20.77             70.01       [==========..]
-Unpori.grog.bodityi              18.05             60.97       [=========...]
-Uperti.ampilyon.extedes          22.23             74.86       [===========.]
+	// Generate a 4-word passphrase
+	passphrase, entropy := gen.GenPassphrase(4) 
+
+	fmt.Println("Passphrase:", passphrase) //e.g. netica.peroundl.opantmene.symnals
+	fmt.Println("Entropy:", entropy)
+}
 ```
 
-1. **Generate passphrases with custom pattern**:
+Want more control over the pattern? Use `GenFromPattern`:
 
-```bash
-genpw -p "WW20dds" -n 5
+```go
+// Generate a password with pattern: Word-Number-Symbol
+pass, entropy := gen.GenFromPattern("w-d-s") // eg. opantmene-4-%
+fmt.Println("Generated Password:", pass)
 ```
 
-The output might look like:
+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 "\".
 
-```bash
-Passphrase               Log10(Guesses)    Log2Entropy      Strength
-
-HandmarmOvera2053"          16.24             54.96       [========....]
-ResabledAnverbou2004+       19.22             64.85       [==========..]
-RocraryiRegonede2072!       19.96             67.29       [==========..]
-SagureraHassain2045-        19.70             66.45       [==========..]
-WoutbDemitte2019#           15.37             52.07       [========....]
-```
+---
 
-or
+## Custom Word Lists
 
-```bash
-genpw -p "w.w.w.w" -n 5
-```
+You can customize the word style by creating a new instance from your own token set:
 
-The output might look like:
+```go
+myTokens := []string{"alpha", "bravo", "charlie", "delta"}
+gen := cryptipass.NewInstanceFromList(myTokens)
 
-```bash
-Passphrase                               Log10(Guesses)    Log2Entropy      Strength
-                                                                           
-cleatabit.sphongedi.zedizmobl.drooky        32.40             108.62      [============]
-comprewa.cedivet.refyerm.unancling          31.19             104.61      [============]
-eitispayi.woblyoffo.unounde.pradimisf       35.27             118.18      [============]
-juiselid.partu.ovenes.slampos               28.32             95.08       [============]
-yaholl.boort.rentlestu.hustfierm            29.38             98.61       [============]
+pass, entropy := gen.GenPassphrase(3)
+fmt.Println("Custom Passphrase:", pass) //e.g. alphar.bravo.delta
+fmt.Println("Entropy:", entropy)
 ```
 
-### Entropy Considerations
-
-Each password generated by CryptiPass comes with an exact entropy evaluation . For example:
-- A 4-word passphrase (pattern "wwww") has on average 97 bits of entropy.
-- A 6-word passphrase (pattern "wwwwww") has on average 146 bits of entropy.
+---
 
-This allows for highly secure passphrases, even against brute-force attacks.
+## Documentation
 
-## Contributing
+Full API documentation is available at [GoDoc](https://pkg.go.dev/github.com/francescoalemanno/cryptipass).
 
-Contributions are welcome! Please open an issue or submit a pull request via the [main repository](https://github.com/francescoalemanno/cryptipass).
+---
 
 ## License
 
-This tool is open-source and 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.
 
-## Contact
+---
 
-For any questions, issues, or suggestions, please visit the [issue tracker](https://github.com/francescoalemanno/cryptipass/issues) on GitHub.
+**cryptipass** – Secure, flexible, and pronounceable passphrases for your Go applications.
diff --git a/cryptipass.go b/cryptipass.go
@@ -31,11 +31,16 @@ func distill(tokens []string) map[string]Transition {
 		}
 		transition_matrix[str][r]++
 	}
-
 	for _, w := range tokens {
-		R := []rune(w)
-		put("lengths", rune(len(R)))
+		R := []rune(strings.ToLower(w))
+		if len(R) == 0 {
+			continue
+		}
+		put("LENGTHS", rune(len(R)))
 		put("", R[0])
+		if len(R) == 1 {
+			continue
+		}
 		put(string(R[0]), R[1])
 		for i := 0; i < len(R)-2; i++ {
 			put(string(R[i])+string(R[i+1]), R[i+2])
@@ -72,7 +77,7 @@ type generator struct {
 	JumpTable *map[string]Transition
 }
 
-// NewInstanceFromList generates a new passphrase generator using a custom
+// NewInstanceFromList returns a new passphrase generator using a custom
 // list of tokens (words). It uses the ChaCha8 random number generator seeded
 // by cryptographically secure random bytes.
 func NewInstanceFromList(tokens []string) *generator {
@@ -93,7 +98,7 @@ func NewInstanceFromList(tokens []string) *generator {
 // NewInstance returns a new passphrase generator initialized with a default
 // wordlist. It uses the ChaCha8 random number generator for randomization.
 func NewInstance() *generator {
-	return NewInstanceFromList(eff_long_word_list)
+	return NewInstanceFromList(eff_short_word_list_2_0)
 }
 
 // GenPassphrase generates a passphrase consisting of the specified number of
@@ -251,7 +256,7 @@ retry:
 // transition matrix of word lengths. It ensures the generated word has an
 // appropriate length and entropy.
 func (g *generator) PickLength() (int, float64) {
-	tr, ok := (*g.JumpTable)["lengths"]
+	tr, ok := (*g.JumpTable)["LENGTHS"]
 	if ok {
 		N := g.Rng.IntN(tr.Total)
 		for i, v := range tr.Counts {

diff --git a/eff_long_word_list.go b/eff_long_word_list.go