PlugBodyDigest (plug_body_digest v0.7.0) View Source

Plug to verify the request body against the digest value sent in the HTTP 'Digest' header, as defined in RFC3230, section 4.3.2.

Supported digests are "sha-512", "sha-256" and "sha".

Options

:on_success - an optional callback for updating the Plug.Conn state upon success; possible values include:
- nil (the default) - do nothing
- {m, f, a} - call the function identified by the atom f in module m; the function receives the current Plug.Conn struct along with any additional parameters in the list a, and is expected to return the updated Plug.Conn struct; see the example below
:on_failure - an optional callback for updating the Plug.Conn state upon failure; possible values include:
- {PlugBodyDigest, :failure, []} (the default) - halt the connection with an appropriate response; see failure/3 below
- {PlugBodyDigest, :optional, []} - make the 'Digest' header optional; see optional/3 below
- {m, f, a} - call the function identified by the atom f in module m; the function receives the current Plug.Conn struct, the error reason (see error_reason/0) and the algorithm list (a string, for possible use in a 'Want-Digest' response header) along with any additional parameters in the list a, and is expected to return the updated Plug.Conn struct
- nil - do nothing

Example

# Update the Plug.Parsers configuration, adding the `:body_reader`
# option:
plug Plug.Parsers,
  parsers: [:urlencoded, :json],
  body_reader: {PlugBodyDigest, :digest_body_reader, []},
  json_decoder: Jason

# Invoke PlugBodyDigest after Plug.Parsers
plug PlugBodyDigest,
  on_success: {Plug.Conn, :assign, [:valid_digest, true]},
  on_failure: {PlugBodyDigest, :optional, []}

Link to this section Summary

Types

error_reason()

Error reasons, passed to the failure callback.

final_digest()

Algorithm and final digest value

Functions

digest_body_reader(conn, read_opts, digest_opts \\ [])

Custom request body reader for Plug.Parsers, updating the digest value(s) while the request body is being read.

failure(conn, reason, want_digest)

The default failure function.

get_digest(conn)

Returns the request body digest.

optional(conn, reason, want_digest)

An alternative failure handler function, allowing requests without a 'Digest' request header.

Link to this section Types

error_reason()

Specs

error_reason() ::
  :body_not_read
  | :multipart
  | :bad_algorithm
  | :no_digest_header
  | :algorithm_mismatch
  | :malformed_digest_value
  | :digest_mismatch

Error reasons, passed to the failure callback.

Server errors:

:body_not_read - the request body was not read, because the request's 'Content-Type' is not handled by Plug.Parsers; see digest_body_reader/3
:multipart - the request contained a multipart content-type, which is not supported by PlugBodyDigest; see digest_body_reader/3
:bad_algorithm - the digest function invocation failed for the selected algorithm; verify that the :crypto application was started and that it supports the necessary algorithms

Client errors:

:no_digest_header - no 'Digest' header was included in the request
:algorithm_mismatch - none of the supported digest algorithms was included in the 'Digest' request header
:malformed_digest_value - the digest value in the 'Digest' request header could not be decoded
:digest_mismatch - the calculated digest value for the request body does not match the expected value specified in the 'Digest' request header

final_digest()

Specs

final_digest() :: {:crypto.hash_algorithm(), binary()}

Algorithm and final digest value

Link to this section Functions

digest_body_reader(conn, read_opts, digest_opts \\ [])

Specs

digest_body_reader(Plug.Conn.t(), Keyword.t(), Keyword.t()) ::
  {:ok, binary(), Plug.Conn.t()}
  | {:more, binary(), Plug.Conn.t()}
  | {:error, term()}

Custom request body reader for Plug.Parsers, updating the digest value(s) while the request body is being read.

Add or update Plug.Parsers (e.g. in the application's Phoenix endpoint) with the :body_reader option:

plug Plug.Parsers,
  parsers: [:urlencoded, :json],
  body_reader: {PlugBodyDigest, :digest_body_reader, []},
  json_decoder: Jason

Only works for parsers that respect the :body_reader option, including Plug.Parsers.URLENCODED and Plug.Parsers.JSON. Not supported are Plug.Parsers.MULTIPART and content types that are ignored by Plug.Parsers through the :pass option.

failure(conn, reason, want_digest)

Specs

failure(Plug.Conn.t(), error_reason(), String.t()) :: Plug.Conn.t()

The default failure function.

It logs an error, returns a 500 'Server Error' response and halts the connection in the following scenarios:

If the request body was not read, because the request's 'Content-Type' is not handled by Plug.Parsers; see digest_body_reader/3
If the digest function invocation failed for the selected algorithm

Otherwise logs the failure, returns a 403 'Forbidden' response with a 'Want-Digest' response header listing the supported algorithms, and halts the connection.

get_digest(conn)

Specs

get_digest(Plug.Conn.t()) ::
  {:ok, PlugBodyDigest.Crypto.final_digest() | nil} | {:error, error_reason()}

Returns the request body digest.

Returns an error if the digest value was not calculated, e.g. because an invalid algorithm was selected. The algorithm is selected based on the Digest header sent by the client or, if it is absent, the first configured algorithm (SHA-256 by default).

Note that this function may only be used if the Plug was previously called; it is not sufficient to enable only the body reader hook.

In tests this function returns a nil digest if the request body was not a binary. Please refer to the Testing section of the project's README.

optional(conn, reason, want_digest)

Specs

optional(Plug.Conn.t(), error_reason(), String.t()) :: Plug.Conn.t()

An alternative failure handler function, allowing requests without a 'Digest' request header.

All other errors are handled as described for failure/3.