README.md

# Expwd

Structure and functions to work with **application passwords** in Elixir

Application passwords can be used by applications (services, servers, machines...) to
authenticate to each other, as for example the HTTP Basic authentication scheme.

This library provides:
- Function to securely compare application password. Such comparison must be performed in constant time for cleartext password ([details about this attack](https://codahale.com/a-lesson-in-timing-attacks/))
- Functions to work with hashed application passwords. In many cases, it is indeed *not* necessary to store the cleartext password on the server: a hashed version is sufficient (as for *user* passwords).

## Installation

```elixir
def deps do
  [
    {:expwd, "~> 1.0"}
  ]
end
```

## Security considerations

**Do not use Expwd for user passwords**, which are typically weak and must be processed with special care (salt and different classes of hashing functions).

All application passwords used and generated by Expwd shall be long and generated in a random manner.

## Examples

```elixir

iex> {pwd, hashedpwd} = Expwd.Hashed.gen()
{"ZxWmjhb3qhTBLFrMgVUEI7LOYW3cvffXd8IivdxWWV0",
 %Expwd.Hashed{
   alg: :sha256,
   hash: <<58, 41, 140, 143, 225, 47, 17, 125, 45, 76, 46, 61, 47, 218, 172, 73,
     241, 142, 78, 207, 59, 188, 148, 154, 6, 209, 23, 206, 235, 119, 39, 37>>
 }}

iex> Expwd.Hashed.Portable.to_portable( %Expwd.Hashed{
...>    alg: :sha256,
...>    hash: <<58, 41, 140, 143, 225, 47, 17, 125, 45, 76, 46, 61, 47, 218, 172, 73,
...>      241, 142, 78, 207, 59, 188, 148, 154, 6, 209, 23, 206, 235, 119, 39, 37>>
...>  })
"expwd:sha256:OimMj+EvEX0tTC49L9qsSfGOTs87vJSaBtEXzut3JyU"

iex> Expwd.Hashed.Portable.from_portable("expwd:sha256:xSE6MkeC+gW7R/lEZKxsWGDs1MlqEV4u693fCBNlV4g") 
%Expwd.Hashed{
  alg: :sha256,
  hash: <<197, 33, 58, 50, 71, 130, 250, 5, 187, 71, 249, 68, 100, 172, 108, 88,
    96, 236, 212, 201, 106, 17, 94, 46, 235, 221, 223, 8, 19, 101, 87, 136>>
}

```