Caracola.Digest (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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.

Summary

Types

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

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

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

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

Functions

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

The strongest algorithm first (RFC 8760 §2.4).

Generates a WWW-Authenticate or Proxy-Authenticate value.

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

Parses a challenge or credentials header value.

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

Calculates the digest response value.

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

Types

algorithm()

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

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

params()

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

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

password()

@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()

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

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

Functions

authorization(challenge, opts)

@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(algorithms)

@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(realm, nonce, opaque \\ nil, algorithm \\ :md5)

@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(user, password, realm, algorithm \\ :md5)

@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(bin)

@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(headers)

@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(method, uri, ha1, nonce, opts \\ [])

@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(credentials, method, password, algorithms \\ [:md5])

@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.