Uses AEGIS to [AEAD][ae] encrypt the _secret_
[`plaintext`][crate::easy::Plaintext] to a byte vector (AKA "encrypted payload")
containing the _public_ nonce, ciphertext and authentication tag.
[`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).
This function internally generates a secure and unique nonce for each call.
The [`decrypt`][crate::easy::decrypt] function can be used to decrypt the
byte vector this function produces.
The structure of the returned byte vector:[^1]
```text
nonce || ciphertext || authentication tag
(32 bytes) (length of plaintext) (32 bytes)
```
This function _requires_ the `rand` Cargo feature (it is enabled by default).
# Implementation Details
This function internally uses the [AEGIS-256X4 cipher][spec] with a 256 bit
authentication tag.
The maintainers of this crate stipulate that any changes to:
- the used AEGIS cipher,
- the byte vector framing, format, or field order,
would be accompanied by a major version number increment. (Our intention is to
_never_ make such changes short of security issues.)
The 256-bit nonce is generated using a cryptographically secure random number
generator provided by the OS, which is assumed to be safe across
[`fork()`][fork].
# Errors
- Returns [`Error::RandError`][crate::easy::Error] in case of errors from the
underlying CSRNG library.
- Returns [`Error::InputBufferWrongSize`][crate::easy::Error] if the length of
`plaintext` plus the lengths of the nonce and authentication tag is greater
than `isize::MAX` (the payload [`Vec`] cannot be allocated).
[ae]: https://en.wikipedia.org/wiki/Authenticated_encryption
[spec]: https://www.rfc-editor.org/rfc/rfc10032.html
[fork]: https://en.wikipedia.org/wiki/Fork_(system_call)