# `BoxTurtle.Security.Password`
[🔗](https://github.com/twajjo/box_turtle/blob/v0.1.0/lib/security/password.ex#L1)

Generates random passwords containing at least one lowercase letter, one uppercase letter,
one digit and one special character.

All randomness comes from `:crypto.strong_rand_bytes/1` (through `:crypto.rand_seed_s/0`),
so the passwords are suitable for credentials. The caller's `:rand` seed is not touched.

    alias BoxTurtle.Security.Password

    {:ok, password} = Password.generate(16)
    String.length(password)  #=> 16
    {:error, :too_short} = Password.generate(4)

    # e.g. a temporary password for an account created by an admin
    def create_invited_user(attrs) do
      {:ok, password} = Password.generate(20)
      attrs |> Map.put(:password, password) |> MyApp.Accounts.register_user()
    end

The approach is inspired by the Rosetta Code
[Password generator](https://rosettacode.org/wiki/Password_generator) task.

# `generate`

```elixir
@spec generate(integer()) :: {:ok, String.t()} | {:error, :too_short}
```

Generates a random password of `length` characters (default 8).

Returns `{:ok, password}`, or `{:error, :too_short}` when `length` is not an integer of at
least 8.

# `min_length`

```elixir
@spec min_length() :: pos_integer()
```

Returns the minimum password length accepted by `generate/1` (8).

---

*Consult [api-reference.md](api-reference.md) for complete listing*