Uses AEGIS to [AEAD][ae] decrypt the _public_ ciphertext stored in
[`buffer`][crate::easy::Ciphertext] _in place_; `buffer` contains the
_secret_ plaintext after successful decryption.
(The module name specifies the used AEGIS algorithm variant.)
[`auth_tag`][crate::easy::AuthTag] must contain the _public_ authentication
tag produced during encryption. It is used to authenticate the ciphertext and
the associated data.
[`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.
[`key`][crate::easy::Key] is the _secret_ encryption key that was used during
encryption.
[`nonce`][crate::careful::Nonce] is the _public_ "number used only once" that
was used during encryption.
<div class="warning">
To avoid catastrophic system compromise, the provided `nonce` must <span
style="color: red; font-weight: bold">NEVER</span> be re-used to encrypt a
different `plaintext` with the same `key`.
</div>
This function never allocates heap memory.
# Errors
- Returns [`Error::AuthTagInvalid`][crate::easy::Error] if the
provided `auth_tag` does not match the computed authentication tag. The entire
`buffer` is zeroed out (as required by RFC 10032).
[ae]: https://en.wikipedia.org/wiki/Authenticated_encryption