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
@type algorithm() :: :md5 | :sha256 | :sha512_256
A digest algorithm: MD5, SHA-256 or SHA-512/256 (RFC 8760).
@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.
A password: the clear text, or a precomputed {:ha1, hash} (optionally with its algorithm).
@type qop() :: :auth | :auth_int | String.t()
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).
Options:
:methodand:uri(binary orCaracola.URI) of the request (required).:userand:password(required).:cnonce(random if not given) and:nc(integer, default1).
Returns :error if the challenge is invalid, uses an unsupported
algorithm or qop, or the password is an HA1 for another algorithm.
The strongest algorithm first (RFC 8760 §2.4).
iex> Caracola.Digest.by_strength([:md5, :sha512_256, :sha256])
[:sha512_256, :sha256, :md5]
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")
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"
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}}
@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.
@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.
@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.