Skip to content

Commit

Permalink
fix README mixup
Browse files Browse the repository at this point in the history
  • Loading branch information
Aizen committed Oct 6, 2024
1 parent c8ee829 commit 7652df7
Show file tree
Hide file tree
Showing 2 changed files with 133 additions and 125 deletions.
110 changes: 56 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,44 @@
# 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 structure**: The number of words, symbols, digits 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 `GenPassphrase` 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
Expand All @@ -40,72 +49,65 @@ import (
)

func main() {
cp := cryptipass.NewInstance()
passphrase, entropy := cp.GenPassphrase(5)
fmt.Printf("Passphrase: %s\n", passphrase)
fmt.Printf("Entropy: %.2f bits\n", entropy)
}
```
// Create a new cryptipass generator
gen := cryptipass.NewInstance()

### Example Output:
// Generate a 4-word passphrase
passphrase, entropy := gen.GenPassphrase(4)

```
Passphrase: ardram.iondbagro.anhambler.scheemous.chmedi
Entropy: 133.21 bits
fmt.Println("Passphrase:", passphrase) //e.g. netica.peroundl.opantmene.symnals
fmt.Println("Entropy:", entropy)
}
```

### Generate a Password according to a pattern
Want more control over the pattern? Use `GenFromPattern`:

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.
```go
// 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 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:
## Custom Word Lists

```go
package main
You can customize the word style by creating a new instance from your own token set:

import (
"fmt"
"github.com/francescoalemanno/cryptipass"
)
```go
myTokens := []string{"alpha", "bravo", "charlie", "delta"}
gen := cryptipass.NewInstanceFromList(myTokens)

func main() {
cp := cryptipass.NewInstance()
passphrase, entropy := cp.GenFromPattern("W-w.cccc.CCCC(ss)[20dd]")
fmt.Printf("Passphrase: %s\n", passphrase)
fmt.Printf("Entropy: %.2f bits\n", entropy)
}
pass, entropy := gen.GenPassphrase(3)
fmt.Println("Custom Passphrase:", pass) //e.g. alphar.bravo.delta
fmt.Println("Entropy:", entropy)
```

### Example Output:
---

```
// pattern W - w .cccc.CCCC(ss)[20dd]
Passphrase: Storegu-dedudend.skin.EALR(=*)[2045]
Entropy: 96.41 bits
```
## Documentation

## Notes
Full API documentation is available at [GoDoc](https://pkg.go.dev/github.com/francescoalemanno/cryptipass).

- The package seeds the random number generator with `crypto/rand`, making it cryptographically secure.
- 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.
---

## Contributing
## License

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.
`cryptipass` is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## License
---

## Contributing

This project is licensed under the MIT License.
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.
148 changes: 77 additions & 71 deletions cmd/genpw/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,111 +1,117 @@
# cryptipass
# genpw - CryptiPass CLI

[![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)
`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.

**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.

---
This tool is part of the [CryptiPass](https://github.com/francescoalemanno/cryptipass) project and resides in the `cmd/genpw` subdirectory.

## 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).

---
- **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.

## Installation

To install `cryptipass`, use `go get`:
To install the `genpw` CLI, first ensure you have Go installed. Then run:

```bash
go get github.com/francescoalemanno/cryptipass
go install github.com/francescoalemanno/cryptipass/cmd/genpw@latest
```

Then, import it into your project:

```go
import "github.com/francescoalemanno/cryptipass"
```

---

## Quick Start
This will install the `genpw` binary in your `$GOPATH/bin` directory.

Here's how to generate a passphrase using the default word style:
## Usage

```go
package main
Once installed, you can generate passphrases by running `genpw` with the following options:

import (
"fmt"
"github.com/francescoalemanno/cryptipass"
)
```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")
```

func main() {
// Create a new cryptipass generator
gen := cryptipass.NewInstance()
### Example Commands

// Generate a 4-word passphrase
passphrase, entropy := gen.GenPassphrase(4)
1. **Generate 6 passphrases with 3 words each** (default):

fmt.Println("Passphrase:", passphrase) //e.g. netica.peroundl.opantmene.symnals
fmt.Println("Entropy:", entropy)
}
```bash
genpw
```

Want more control over the pattern? Use `GenFromPattern`:
This will output something like:

```go
// Generate a password with pattern: Word-Number-Symbol
pass, entropy := gen.GenFromPattern("w-d-s") // eg. opantmene-4-%
fmt.Println("Generated Password:", pass)
```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 [===========.]
```

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 "\".
1. **Generate passphrases with custom pattern**:

---
```bash
genpw -p "WW20dds" -n 5
```

## Custom Word Lists
The output might look like:

You can customize the word style by creating a new instance from your own token set:
```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 [========....]
```
```go
myTokens := []string{"alpha", "bravo", "charlie", "delta"}
gen := cryptipass.NewInstanceFromList(myTokens)
or
pass, entropy := gen.GenPassphrase(3)
fmt.Println("Custom Passphrase:", pass) //e.g. alphar.bravo.delta
fmt.Println("Entropy:", entropy)
```bash
genpw -p "w.w.w.w" -n 5
```
---
The output might look like:
## Documentation
```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 [============]
```
Full API documentation is available at [GoDoc](https://pkg.go.dev/github.com/francescoalemanno/cryptipass).
### 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.
## License
This allows for highly secure passphrases, even against brute-force attacks.
`cryptipass` is licensed under the MIT License. See [LICENSE](LICENSE) for details.
## Contributing
---
Contributions are welcome! Please open an issue or submit a pull request via the [main repository](https://github.com/francescoalemanno/cryptipass).
## Contributing
## License
Contributions, issues, and feature requests are welcome! Feel free to check out [issues](https://github.com/francescoalemanno/cryptipass/issues) or open a pull request.
This tool is open-source and licensed under the MIT License.
---
## Contact
**cryptipass** – Secure, flexible, and pronounceable passphrases for your Go applications.
For any questions, issues, or suggestions, please visit the [issue tracker](https://github.com/francescoalemanno/cryptipass/issues) on GitHub.

0 comments on commit 7652df7

Please sign in to comment.