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 thePlug.Conn
state upon success; possible values include::on_failure
- an optional callback for updating thePlug.Conn
state upon failure; possible values include:{PlugBodyDigest, :failure, []}
(the default) - halt the connection with an appropriate response; seefailure/3
below{PlugBodyDigest, :optional, []}
- make the 'Digest' header optional; seeoptional/3
below{m, f, a}
- call the function identified by the atomf
in modulem
; the function receives the currentPlug.Conn
struct, the error reason (seeerror_reason/0
) and the algorithm list (a string, for possible use in a 'Want-Digest' response header) along with any additional parameters in the lista
, and is expected to return the updatedPlug.Conn
structnil
- 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
error_reason()
View Sourceerror_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 byPlug.Parsers
; seedigest_body_reader/3
:multipart
- the request contained a multipart content-type, which is not supported byPlugBodyDigest
; seedigest_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
digest_body_reader(conn, read_opts, digest_opts \\ [])
View Sourcedigest_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)
View Sourcefailure(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
; seedigest_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.
optional(conn, reason, want_digest)
View Sourceoptional(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
.