# 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__ characters are uppercase (A-Z) and lowercase (a-z) ascii. Any set of unique characters (including Unicode) can be specified:

  iex> alphas = "dđiînñgğoøsşkķyŷ"
  iex> defmodule(CustomAlphaPassword, do: use(RandomPassword, alpha: 12, symbol: 3, alphas: alphas))
  iex> CustomAlphaPassword.generate()

Symbol characters can also be explicitly specified:

  iex> defmodule(CustomSymbolsPassword, do: use(RandomPassword, alpha: 10, decimal: 3, symbol: 3, symbols: "@#$%&!"))
  iex> CustomSymbolsPassword.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.1"}

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`, __decimal__ 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 setting of `alphas` and `symbols` characters to not overlap with either each other or the fixed __decimal__ characters, 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.