# `Caracola.Digest`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/digest.ex#L1)

Digest authentication (RFC 2617, and RFC 7616 and RFC 8760 for the SHA-2
algorithms), with `qop=auth`. Port of the stateless part of NkSIP's
`nksip_auth`: parsing of `WWW-Authenticate`, `Proxy-Authenticate`,
`Authorization` and `Proxy-Authorization` values, generation of challenges
and credentials, and verification.

The algorithms are `:md5`, `:sha256` (`SHA-256`) and `:sha512_256`
(`SHA-512-256`). Nonce generation and tracking is left to the caller.

Unlike NkSIP, the realm keeps its case (it is part of the HA1 hash) and
quoted values are unescaped.

Passwords can be given in clear text or as a precomputed HA1 (the result
of `ha1/4`), so that clear passwords don't need to be stored:
`{:ha1, algorithm, hex}`, or `{:ha1, hex}` for MD5. An HA1 is only valid
for its algorithm.

# `algorithm`

```elixir
@type algorithm() :: :md5 | :sha256 | :sha512_256
```

A digest algorithm: MD5, SHA-256 or SHA-512/256 (RFC 8760).

# `params`

```elixir
@type params() :: %{
  optional(:scheme) =&gt; :digest | :basic | String.t(),
  optional(:realm) =&gt; String.t(),
  optional(:nonce) =&gt; String.t(),
  optional(:opaque) =&gt; String.t(),
  optional(:username) =&gt; String.t(),
  optional(:uri) =&gt; String.t(),
  optional(:response) =&gt; String.t(),
  optional(:cnonce) =&gt; String.t(),
  optional(:nc) =&gt; String.t(),
  optional(:algorithm) =&gt; algorithm() | String.t(),
  optional(:qop) =&gt; [qop()],
  optional(String.t()) =&gt; String.t()
}
```

The parameters of a `WWW-Authenticate`, `Authorization` or similar header, as a map.

# `password`

```elixir
@type password() :: String.t() | {:ha1, String.t()} | {:ha1, algorithm(), String.t()}
```

A password: the clear text, or a precomputed `{:ha1, hash}` (optionally with its algorithm).

# `qop`

```elixir
@type qop() :: :auth | :auth_int | String.t()
```

A quality of protection: `:auth`, `:auth_int` or another token.

# `authorization`

```elixir
@spec authorization(binary() | params(), keyword()) :: {:ok, String.t()} | :error
```

Generates an `Authorization` or `Proxy-Authorization` value to answer
`challenge` (a header value or its parsed form).

Options:

  * `:method` and `:uri` (binary or `Caracola.URI`) of the request (required).
  * `:user` and `:password` (required).
  * `:cnonce` (random if not given) and `:nc` (integer, default `1`).

Returns `:error` if the challenge is invalid, uses an unsupported
algorithm or qop, or the password is an HA1 for another algorithm.

# `by_strength`

```elixir
@spec by_strength([algorithm()]) :: [algorithm()]
```

The strongest algorithm first (RFC 8760 §2.4).

    iex> Caracola.Digest.by_strength([:md5, :sha512_256, :sha256])
    [:sha512_256, :sha256, :md5]

# `challenge`

```elixir
@spec challenge(String.t(), String.t(), String.t() | nil, algorithm()) :: String.t()
```

Generates a `WWW-Authenticate` or `Proxy-Authenticate` value.

    iex> Caracola.Digest.challenge("example.com", "n1", "o1")
    ~S(Digest realm="example.com", nonce="n1", algorithm=MD5, qop="auth", opaque="o1")
    iex> Caracola.Digest.challenge("example.com", "n1", nil, :sha256)
    ~S(Digest realm="example.com", nonce="n1", algorithm=SHA-256, qop="auth")

# `ha1`

```elixir
@spec ha1(String.t(), password(), String.t(), algorithm()) :: String.t() | nil
```

Calculates the HA1 hash (`H(user:realm:password)`) as lowercase hex, or
returns the precomputed one (`nil` if it is for another algorithm).

    iex> Caracola.Digest.ha1("user", "pass", "realm")
    "8493fbc53ba582fb4c044c456bdc40eb"
    iex> Caracola.Digest.ha1("Mufasa", "Circle of Life", "http-auth@example.org", :sha256)
    "7987c64c30e25f1b74be53f966b49b90f2808aa92faf9a00262392d7b4794232"

# `parse`

```elixir
@spec parse(binary()) :: {:ok, params()} | :error
```

Parses a challenge or credentials header value.

    iex> Caracola.Digest.parse(~S(Digest realm="Example", nonce="abc", qop="auth,auth-int", algorithm=md5))
    {:ok, %{scheme: :digest, realm: "Example", nonce: "abc", qop: [:auth, :auth_int], algorithm: :md5}}

# `realms`

```elixir
@spec realms(Caracola.Message.t() | [{String.t(), String.t()}]) :: [String.t()]
```

Extracts the realms of all the `WWW-Authenticate` and `Proxy-Authenticate`
headers of a response.

# `response`

```elixir
@spec response(
  Caracola.Message.method(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: String.t()
```

Calculates the digest `response` value.

Without `:qop` the RFC 2069 form is used. With `qop: :auth`, the `:cnonce`
and `:nc` (as sent on the wire, eight hex digits) options are required.
The `:algorithm` option is `:md5` by default.

# `verify`

```elixir
@spec verify(params(), Caracola.Message.method(), password(), [algorithm()]) ::
  boolean() | :invalid
```

Verifies parsed credentials (from `Authorization` or
`Proxy-Authorization`) for a request with `method` and the user's password.

Returns `:invalid` if the credentials are not digest with `qop=auth`,
their algorithm is not in `algorithms` (default `[:md5]`), some field is
missing, or the password is an HA1 for another algorithm. Checking that the
nonce was generated by us, and its expiration, is up to the caller.

---

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