Uses AEGIS to [AEAD][ae] decrypt the ciphertext and authentication tag
referenced by [`ciphertext_with_tag`][crate::easy::Ciphertext] to a byte vector
containing the _secret_ plaintext.
(The module name specifies the used AEGIS algorithm variant.)
[`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.
[`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>
If you are seeing unexpected
[`Error::AuthTagInvalid`][crate::easy::Error] errors when calling
this function, it is most likely because:
- The [`ciphertext_with_tag`][crate::easy::Ciphertext] doesn't have an appended
authentication tag,
- The appended authentication tag isn't the correct size. Make sure the provided
`Tag` generic parameter matches the one used during encryption.
# Errors
- Returns [`Error::AuthTagInvalid`][crate::easy::Error] if the
provided `auth_tag` does not match the computed authentication tag.
- Returns [`Error::InputBufferWrongSize`][crate::easy::Error] if
the `ciphertext_with_tag` has the wrong size. Keep in mind
`ciphertext_with_tag` must contain a _ciphertext_ and an appended
_authentication tag_ whose length is chosen with the `Tag` generic parameter.
[ae]: https://en.wikipedia.org/wiki/Authenticated_encryption