Uses AEGIS to [AEAD][ae] encrypt the _secret_ plaintext stored in
[`buffer`][crate::easy::PlaintextMut] _in place_; `buffer` contains the
_public_ ciphertext after successful encryption.
(The module name specifies the used AEGIS algorithm variant.)
[`associated_data`][crate::easy::AssociatedData] (which can be empty; see
[`AssociatedData::EMPTY`][crate::easy::AssociatedData::EMPTY]) is _public_
"additional associated data" that the sender will provide along with the
ciphertext to the receiver. This data is NOT _encrypted_, but it is
_authenticated_ along with the ciphertext during decryption.
[`key`][crate::easy::Key] is the _secret_ encryption key that MUST be randomly
generated from a cryptographically secure random number generated (CSRNG).
[`nonce`][crate::careful::Nonce] is the _public_ "number used only once" which
adds (required!) output unpredictability. This parameter is taken by-value to
make it harder to accidentally reuse the nonce.
<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>
The returned _public_ [authentication tag][crate::easy::AuthTag] authenticates
`associated_data` and the ciphertext written to `buffer` during decryption.
Using the `Tag` generic parameter, the caller can choose a 128 or 256 bits long
authentication tag.
This function never allocates heap memory.
# Errors
- Currently _none_, but `Result` is returned to avoid API breaking changes if
errors need to be returned in the future.
[ae]: https://en.wikipedia.org/wiki/Authenticated_encryption