Uses AEGIS to [AEAD][ae] decrypt the _public_ `encrypted_payload` created by the
[`encrypt`][crate::easy::encrypt] function into the _secret_ plaintext.
[`associated_data`][crate::easy::AssociatedData] is _public_ "additional
associated data" that the sender used during encryption and provided along with
the ciphertext to the receiver. This data is authenticated along with
the ciphertext bytes.
[`key`][crate::easy::Key] is the _secret_ encryption key that was used during
encryption.
If you are seeing unexpected
[`Error::AuthTagInvalid`][crate::easy::Error] errors when calling
this function, it is most likely because the `encrypted_payload` doesn't contain
all the bytes that [`encrypt`][crate::easy::encrypt] produced. It _must_ equal
the full `nonce || ciphertext || authentication tag`[^1] bytes, not just the
ciphertext. See the docs for [`encrypt`][crate::easy::encrypt].
# Errors
- Returns [`Error::AuthTagInvalid`][crate::easy::Error] if the
`auth_tag` in the `encrypted_payload` does not match the computed
authentication tag.
- Returns [`Error::InputBufferWrongSize`][crate::easy::Error] if
the `encrypted_payload` has the wrong size, likely because it's not respecting
the expected structure of the payload (see [`encrypt`][crate::easy::encrypt]).
[ae]: https://en.wikipedia.org/wiki/Authenticated_encryption