cryptipass

README

Cryptipass

NOTE: We also have a CLI 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.

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.

Installation

To use the cryptipass package in your project, you need to install it using Go's package management:

go get github.com/francescoalemanno/cryptipass

Then import it in your Go files:

import "github.com/francescoalemanno/cryptipass"

Usage

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.

Example:

package main

import (
	"fmt"
	"cryptipass"
)

func main() {
	passphrase, entropy := cryptipass.NewPassphrase(5)
	fmt.Printf("Passphrase: %s\n", passphrase)
	fmt.Printf("Entropy: %.2f bits\n", entropy)
}

Example Output:

Passphrase: jesside.flyperm.aunsis.dertsy
Entropy: 97.63 bits

Word Generation

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.

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

Notes

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

Contributing

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.

License

This project is licensed under the MIT License.

---

Happy coding and stay secure with Cryptipass!

Documentation

Overview

Package cryptipass v1.3.0 provides functionality for generating secure passphrases composed of random words, with a focus on cryptographic security and entropy calculation.

Index

• func GenMixWord() (string, float64)
• func GenWord(n int) (string, float64)
• func NewPassphrase(words uint64) (string, float64)
• func PickLength() (int, float64)
• func PickNext(seed string) (string, float64)

Functions

func GenMixWord

func GenMixWord() (string, float64)

GenMixWord generates a single word of random length and returns it along with its entropy. The word length is determined by the PickLength function, and the word itself is generated by the GenWord function.

• Return values: string: The generated word of random length. float64: The entropy contributed by both the word length and the word itself.

func GenWord

func GenWord(n int) (string, float64)

GenWord generates a word of exactly n characters and returns it along with the entropy associated with the process. The characters are selected by calling PickNext iteratively until the word reaches the desired length.

• Parameters: n (int): The number of characters to include in the generated word.

• Return values: string: The generated word consisting of n characters. float64: The total entropy contributed by the character selection process.

func NewPassphrase

func NewPassphrase(words uint64) (string, float64)

NewPassphrase generates a passphrase consisting of the specified number of random words. Each word is chosen by the GenMixWord function, and the total entropy of the passphrase is calculated and returned along with the passphrase.

• Parameters: words (uint64): The number of words to include in the passphrase.

• Return values: string: The generated passphrase, with words joined by periods. float64: The total entropy (in bits) of the passphrase, indicating its strength.

func PickLength

func PickLength() (int, float64)

PickLength returns a random word length and its associated entropy. The word length is chosen based on a weighted random selection, with lengths ranging from 3 to 9 characters.

• Return values: int: The selected word length in characters. float64: The entropy contributed by the length selection process.

func PickNext

func PickNext(seed string) (string, float64)

PickNext appends the next character to the current seed string based on specific rules. It evaluates the last two characters of the seed to decide on the next character, either through predefined cases (such as 'mh' becoming 'mho') or randomly selecting a new character with associated entropy.

• Parameters: seed (string): The current string being used to generate the passphrase.

• Return values: string: The updated string after appending the next character. float64: The entropy contributed by the character selection process.