# RandomPassword

Efficiently generate cryptographically strong random passwords using alpha (including Unicode), decimal and symbol characters.

[![Build Status](](   [![Hex Version]( "Hex Version")](   [![License: MIT](]()

## <a name="TOC"></a>TOC
- [Usage](#Usage)
- [Installation](#Installation)
- [Strategy](#Strategy)

## <a name="Usage"></a>Usage

Create a module for generating random passwords:

  iex> defmodule(DefaultPassword, do: use(RandomPassword))
  iex> DefaultPassword.generate()

By default, `RandomPassword` modules generate passwords comprised of 14 alpha, 2 decimal, and 1 symbol. To specify different character counts, supply any combination of `alpha`, `decimal` or `symbol` during module creation:

  iex> defmodule(StrongPassword, do: use(RandomPassword, alpha: 16, decimal: 4, symbol: 2))
  iex> StrongPassword.generate()

Default __alpha__, __decimal__ and __symbol__ characters are used in creating passwords, but any set of unique characters (including Unicode for __alpha__) can be specified:

  iex> alphas = "dđiînñgğoøsşkķyŷ"
  iex> decimals = "246789"
  iex> symbols = "@#$%&!"
  iex> defmodule(CustomCharsPassword, do: use(RandomPassword, alpha: 12, decimal: 3, symbol: 3, alphas: alphas, decimals: decimals, symbols: symbols))
  iex> CustomCharsPassword.generate()

`RandomPassword` uses [:crypto.strong_rand_bytes/1]( as the default entropy source. The `rand_bytes` option can be used to specify any function of the form `(non_neg_integer) -> binary` as the source:

  iex> defmodule(PrngPassword, do: use(RandomPassword, alpha: 14, decimal: 4, symbol: 3, rand_bytes: &:rand.bytes/1 ))
  iex> PrngPassword.generate()

Each created module includes an `info/0` function to display module parameterization:

  iex> defmodule(StrongPassword, do: use(RandomPassword, alpha: 17, decimal: 3, symbol: 3))
  iex> StrongPassword.generate()
    alpha: 17,
    alphas: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
    decimal: 3,
    decimals: "0123456789",
    entropy_bits: 121.3,
    length: 23,
    symbol: 3,
    symbols: "!#$%&()*+,-./:;<=>?@[]^_{|}~"

## <a name="Installation"></a>Installation

Add `random_password` to `mix.exs` dependencies:

  def deps,
    do: [ 
      {:random_password, "~> 1.2"}

Update dependencies

  mix deps.get


## <a name="Strategy"></a>Strategy

`RandomPassword` uses [`Puid`]( to generate random strings. `Puid` is extremely fast, and by default using cryptographically strong random bytes for random string generation.

Three random strings are generated, one from each of `alphas`, `decimals` and `symbols` characters of length specified by the `alpha`, `decimal` and `symbol` options. These three strings are concatenated and shuffled to form the final random password.

Since `RandomPassword` restricts the optional characters for `alphas`, `decimals` and `symbols` to not overlap, the resulting entropy of the random password is the sum of the entropy for the three separate random strings. The `RandomPassword` module function `info/0` lists the total entropy bits of the generated random passwords.