Skip to content

Commit

Permalink
2.0 release (#1)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@francescoalemanno
francescoalemanno authored Oct 7, 2024
1 parent 5c16201 commit 121cf7c
Show file tree
Hide file tree
Showing 13 changed files with 721 additions and 19,656 deletions.
101 changes: 67 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
115 changes: 62 additions & 53 deletions cmd/genpw/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 121cf7c

Please sign in to comment.