plug_body_digest v0.5.0 PlugBodyDigest 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 reasons, passed to the failure callback.

Functions

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

The default failure function.

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

Link to this section Types

Link to this type

error_reason()

View Source
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

Link to this section Functions

Link to this function

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

View Source
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.

Link to this function

failure(conn, reason, want_digest)

View Source

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.

Link to this function

optional(conn, reason, want_digest)

View Source
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.